> 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/jp/methods/apps/oauth.md).

# oauth

## Authorize a user

<mark style="color:blue;">`GET`</mark> `https://mastodon.example/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. The authorization code can be used while requesting a token to obtain access to user-level methods.

#### Request Body

| Name           | Type   | Description                                                                                                                                                                                                         |
| -------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| force\_login   | string | Added in 2.6.0. Forces the user to re-login, which is necessary for authorizing with multiple accounts from the same instance.                                                                                      |
| response\_type | string | Should be set equal to `code`.                                                                                                                                                                                      |
| client\_id     | string | Client ID, obtained during app registration.                                                                                                                                                                        |
| redirect\_uri  | string | Set a URI to redirect the user to. If this parameter is set to `urn:ietf:wg:oauth:2.0:oob` then the authorization code will be shown instead. Must match one of the redirect URIs declared during app registration. |
| scope          | string | List of requested OAuth scopes, separated by spaces (or by pluses, if using query parameters). Must be a subset of scopes declared during app registration. If not provided, defaults to `read`.                    |

{% tabs %}
{% tab title="200 The authorization code will be returned as a query parameter named code." %}

```http
redirect_uri?code=qDFUEaYrRK5c-HNmTCJbAzazwLRInJ7VHFat0wcMgCU
```

{% endtab %}

{% tab title="400 If the authorization code is incorrect or has been used already, the request will fail." %}

```javascript
{
  "error": "invalid_grant",
  "error_description": "The provided authorization grant is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client."
}
```

{% endtab %}
{% endtabs %}

## Obtain a token

<mark style="color:green;">`POST`</mark> `https://mastodon.example/oauth/token`

Returns an access token, to be used during API calls that are not public.

#### Request Body

| Name           | Type   | Description                                                                                                                                                                                          |
| -------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| client\_id     | string | Client ID, obtained during app registration                                                                                                                                                          |
| client\_secret | string | Client secret, obtained during app registration                                                                                                                                                      |
| redirect\_uri  | string | Set a URI to redirect the user to. If this parameter is set to urn:ietf:wg:oauth:2.0:oob then the token will be shown instead. Must match one of the redirect URIs declared during app registration. |
| scope          | string | List of requested OAuth scopes, separated by spaces. Must be a subset of scopes declared during app registration. If not provided, defaults to `read`.                                               |
| code           | string | A user authorization code, obtained via /oauth/authorize                                                                                                                                             |
| grant\_type    | string | Set equal to `authorization_code` if `code` is provided in order to gain user-level access. Otherwise, set equal to `client_credentials` to obtain app-level access only.                            |

{% tabs %}
{% tab title="200 Store this access\_token for later use with auth-required methods. The token should be passed as an HTTP Authorization header when making API calls, with the value Bearer access\_token" %}

```javascript
{
  "access_token": "ZA-Yj3aBD8U8Cm7lKUp-lm9O9BmDgdhHzDeqsY8tlL0",
  "token_type": "Bearer",
  "scope": "read write follow push",
  "created_at": 1573979017
}
```

{% endtab %}

{% tab title="400 If you try to request a scope that was not included when registering the app, the request will fail." %}

```javascript
{
  "error": "invalid_scope",
  "error_description": "The requested scope is invalid, unknown, or malformed."
}
```

{% endtab %}

{% tab title="401 If client\_id and client\_secret do not match or are invalid, the request will fail." %}

```javascript
{
  "error": "invalid_client",
  "error_description": "Client authentication failed due to unknown client, no client authentication included, or unsupported authentication method."
}
```

{% endtab %}
{% endtabs %}

## Revoke token

<mark style="color:green;">`POST`</mark> `https://mastodon.example/oauth/revoke`

Revoke an access token to make it no longer valid for use.

#### Request Body

| Name           | Type   | Description                                      |
| -------------- | ------ | ------------------------------------------------ |
| client\_id     | string | Client ID, obtained during app registration      |
| client\_secret | string | Client secret, obtained during app registration  |
| token          | string | The previously obtained token, to be invalidated |

{% tabs %}
{% tab title="200 If you own the provided token, the API call will provide an empty response. This operation is idempotent, so calling this API multiple times will still return OK." %}

```javascript
{}
```

{% endtab %}

{% tab title="403 If you provide a token you do not own, or no token at all, the API call will return a 403 error." %}

```javascript
{
  "error": "unauthorized_client",
  "error_description": "You are not authorized to revoke this token"
}
```

{% endtab %}
{% endtabs %}

##


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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/methods/apps/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.