---
description: Generate and manage OAuth tokens.
---

# 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 %}

##
