> For the complete documentation index, see [llms.txt](https://mastodon.gitbook.io/mastodon/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mastodon.gitbook.io/mastodon/spec/oauth.md).

# 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](https://tools.ietf.org/html/rfc6749) 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.

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

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](/mastodon/methods/apps.md#create-an-application) and then [proceed with normal OAuth 2](/mastodon/methods/apps/oauth.md).

## OAuth 2 endpoints implemented <a href="#oauth-2-endpoints" id="oauth-2-endpoints"></a>

The following descriptions are taken from the [Doorkeeper documentation](https://github.com/doorkeeper-gem/doorkeeper/wiki/API-endpoint-descriptions-and-examples). Mastodon uses Doorkeeper to implement OAuth 2. For more information on how to use these endpoints, see the [API documentation for OAuth.](/mastodon/methods/apps/oauth.md)

{% embed url="<https://github.com/tootsuite/mastodon/blob/master/config/initializers/doorkeeper.rb>" %}
Doorkeeper config initializer
{% endembed %}

### [GET /oauth/authorize](/mastodon/methods/apps/oauth.md#authorize-a-user)

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.

### [POST /oauth/token](/mastodon/methods/apps/oauth.md#obtain-a-token) <a href="#post-oauth-token" id="post-oauth-token"></a>

Obtain an access token. This corresponds to the token endpoint, section 3.2 of the OAuth 2 RFC.

### [POST /oauth/revoke](/mastodon/methods/apps/oauth.md#revoke-token) <a href="#post-oauth-revoke" id="post-oauth-revoke"></a>

Post here with client credentials to revoke an access token. This corresponds to the token endpoint, using the OAuth 2.0 Token Revocation RFC (RFC 7009).

## Common gotchas <a href="#common-gotchas" id="common-gotchas"></a>

* 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.