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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://mastodon.gitbook.io/mastodon/jp/spec/oauth.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.