OAuth

What is OAuth?

The Mastodon API has many methods that require authentication from a client or authorization from a user. This is accomplished with OAuth 2.0, an authorization framework described in RFC 6749 that allows third-party applications to obtain limited access to an HTTP service on behalf of a resource owner, through the use of a standardized authorization flow that generates a client access token to be used with HTTP requests.

To obtain an OAuth token for a Mastodon website, make sure that you allow your users to specify the domain they want to connect to before login. Use that domain to acquire a client id/secret and then proceed with normal OAuth 2.

OAuth 2 endpoints implemented

The following descriptions are taken from the Doorkeeper documentation. Mastodon uses Doorkeeper to implement OAuth 2. For more information on how to use these endpoints, see the API documentation for OAuth.

Authorization endpoint (RFC 6749 Section 3.1)

GET /oauth/authorize

Displays an authorization form to the user. If approved, it will create and return an authorization code, then redirect to the desired redirect_uri, or show the authorization code if urn:ietf:wg:oauth:2.0:oob was requested.

Token endpoint (RFC 6749 Section 3.2)

POST /oauth/token

Obtain an access token. Mastodon supports the following OAuth 2 flows:

Authorization code flow

For end-users

Password grant flow

For bots and other single-user applications

Client credentials flow

For applications that do not act on behalf of users

Token revocation endpoint (RFC 7009 Section 2)

POST /oauth/revoke

Post here with client credentials to revoke an access token.

Common gotchas

• When registering an application using Mastodon’s REST API, there is a scopes parameter. When interfacing with OAuth endpoints, you must use the scope parameter instead, and this parameter’s value must be a subset of the scopes registered with the app. You cannot include anything that wasn’t in the original set.
• When registering an application using Mastodon’s REST API, there is a redirect_uris parameter. When interfacing with OAuth endpoints, you must use the redirect_uri parameter instead, and this parameter’s value must be one of the redirect_uris registered with the app.