Skip to main content

OAuth and MiAuth

Misskey offers two ways for an app to get an access token.

OAuth 2.0MiAuth
ServersMisskey v2023.9.0 and laterOlder servers too
client_id pageRequired (HTTPS)Not needed
Where the browser returnsThe redirect_uri listed on the client_id pageyourscheme:// (scheme only)
ConfigurationMisskeyOAuthConfigMisskeyMiAuthConfig

Both methods open the external browser and return to the app through a custom URL scheme, so both need the platform setup.

To check whether a server supports OAuth, call MisskeyOAuthClient().getOAuthServerInfo(host). It returns null when the server does not support OAuth. authenticate and loginWithOAuth throw OAuthNotSupportedException in that case, so you can fall back to MiAuth.

Configuration​

MisskeyOAuthConfig​

ParameterDescription
hostMisskey server host, such as misskey.io
clientIdURL of your client_id page
redirectUriA redirect URI listed on the client_id page, such as yourscheme://oauth/callback
scopeSpace-separated scopes, such as read:account write:notes
callbackSchemeYour app's custom scheme. Required, but used only when redirectUri is an http(s) relay page; otherwise the scheme of redirectUri is used

MisskeyMiAuthConfig​

ParameterDescription
hostMisskey server host
appNameApp name shown to the user
callbackSchemeYour app's custom scheme. Misskey redirects the browser to yourscheme://
permissionsRequested permissions, such as ['read:account', 'write:notes']. Optional
iconUrlURL of the app icon shown to the user. Optional

Without Saving Tokens​

MisskeyOAuthClient and MisskeyMiAuthClient run the flow and return the token. They do not save it.

OAuth​

import 'package:misskey_auth/misskey_auth.dart';

final oauthClient = MisskeyOAuthClient();
final token = await oauthClient.authenticate(
  MisskeyOAuthConfig(
    host: 'misskey.io',
    clientId: 'https://yourpage/yourapp/',
    redirectUri: 'yourscheme://oauth/callback',
    scope: 'read:account write:notes',
    callbackScheme: 'yourscheme',
  ),
);
print(token?.accessToken);

MiAuth​

import 'package:misskey_auth/misskey_auth.dart';

final miClient = MisskeyMiAuthClient();
final result = await miClient.authenticate(
  MisskeyMiAuthConfig(
    host: 'misskey.io',
    appName: 'Your App',
    callbackScheme: 'yourscheme',
    permissions: ['read:account', 'write:notes'],
    iconUrl: 'https://example.com/icon.png', // Optional
  ),
);
print(result.token);
print(result.user); // User information, if the server returns it

With Saving Tokens​

MisskeyAuthManager runs the flow and saves the token with a TokenStore. MisskeyAuthManager.defaultInstance() uses SecureTokenStore. Each login returns an AccountKey that identifies the account.

OAuth​

import 'package:misskey_auth/misskey_auth.dart';

final auth = MisskeyAuthManager.defaultInstance();
final key = await auth.loginWithOAuth(
  MisskeyOAuthConfig(
    host: 'misskey.io',
    clientId: 'https://yourpage/yourapp/',
    redirectUri: 'yourscheme://oauth/callback',
    scope: 'read:account write:notes',
    callbackScheme: 'yourscheme',
  ),
  setActive: true,
);
final current = await auth.currentToken();

After OAuth, the manager calls /api/i with the new token to find the account ID.

MiAuth​

import 'package:misskey_auth/misskey_auth.dart';

final auth = MisskeyAuthManager.defaultInstance();
final key = await auth.loginWithMiAuth(
  MisskeyMiAuthConfig(
    host: 'misskey.io',
    appName: 'Your App',
    callbackScheme: 'yourscheme',
    permissions: ['read:account', 'write:notes'],
    iconUrl: 'https://example.com/icon.png',
  ),
  setActive: true, // Also make this the active account
);
final current = await auth.currentToken();

MiAuth returns user information together with the token, and the manager uses its id as the account ID.

Supporting Both Methods in One App​

  • Register one scheme, such as yourscheme, in Info.plist and AndroidManifest.xml. OAuth and MiAuth can share it.
  • MiAuth calls back to the scheme only (yourscheme://). You do not need a path such as yourscheme://oauth/callback for MiAuth.
  • On Android, keep the scheme-only intent-filter from Platform Setup. A filter restricted by host or path stops MiAuth callbacks from reaching the app.

See Also​