# Getting a token

How a third-party app gets an access token: a client, bot, integration, or command-line tool that uses the client API
(`/api/v1`) of an instance on behalf of its users. The operations of the API are in its OpenAPI document
(see [Stability of the API](https://mycroblog.dev/next/developers/stability/)).

## The flow at a glance

![A sequence diagram of getting a token: the app discovers the server's endpoints, registers, sends the user's browser through the authorization code flow with PKCE, exchanges the code for tokens, and refreshes them. The steps are listed below.](https://github.com/mycroblog/my/blob/main/docs/developers/images/token-flow.svg?raw=true)

From the top of the diagram down, between the app, the user's browser, and the server:

1. **Discovery.** The app fetches `GET /.well-known/oauth-authorization-server` and learns the endpoints, `scopes_supported`,
   and the code challenge method `S256` ([Discovery](#discovery)).
2. **Registration.** The app gets a `client_id`: `POST /oauth/register` answers `201` with one, or the app uses a `client_id`
   URL, or an app a user registered ([Registering an app](#registering-an-app)).
3. **Authorization code with PKCE.** The app makes a `code_verifier` and its `S256` `code_challenge`, and opens the authorize URL
   in the browser. The browser sends `GET /oauth/authorize` with `client_id`, `redirect_uri`, `code_challenge` and `state`; for a
   `client_id` URL, the server fetches its document. The server shows the sign-in and consent screen, the user approves
   (`POST /oauth/authorize`), and the server redirects with `303` to `redirect_uri` with `code`, `state` and `iss`. The browser
   brings them to the app, which checks `state` and `iss` ([Authorization](#authorization)).
4. **Token.** The app sends `POST /oauth/token` with `grant_type=authorization_code`, the `code` and the `code_verifier`, gets an
   `access_token` for 1 hour and a `refresh_token` for 30 days, and calls `/api/v1` with `Authorization: Bearer <access_token>`.
5. **Refresh.** When the access token has expired, the API answers `401` with `error="invalid_token"`. The app sends
   `POST /oauth/token` with `grant_type=refresh_token` and gets a new access token and a new refresh token; the old ones stop
   working ([Tokens](#tokens)).

## Mastodon client libraries do not work as they are

The client API is this project's own. It is **not** the Mastodon client API:

- There is no `POST /api/v1/apps`, and no other Mastodon endpoint. A client library for Mastodon, or for a server that copies its API,
  cannot register itself, authorize, or call this server.
- An app gets a `client_id` in one of three ways ([below](#registering-an-app)). Dynamic client registration is
  [RFC 7591](https://www.rfc-editor.org/rfc/rfc7591) at `POST /oauth/register`.
- Federation with Mastodon, Misskey and Pleroma servers is unaffected: this concerns only the API that apps call.

Any OAuth 2.0 client library that supports the authorization code grant with PKCE can authorize against the server.

## Discovery

An instance publishes two documents, anonymous and cacheable for 5 minutes, so that a generic client can configure itself from the instance's origin:

| URL | Document |
| --- | --- |
| `/.well-known/oauth-authorization-server` | Authorization server metadata ([RFC 8414](https://www.rfc-editor.org/rfc/rfc8414)): the endpoints, `scopes_supported` (the scopes a third party may hold), `code_challenge_methods_supported: ["S256"]`, `grant_types_supported`, and the supported client authentication methods. `registration_endpoint` is present only while dynamic registration is on, and `client_id_metadata_document_supported` only while metadata document clients are on. |
| `/.well-known/oauth-protected-resource` | Protected resource metadata ([RFC 9728](https://www.rfc-editor.org/rfc/rfc9728)) of `/api/v1`. The `WWW-Authenticate` header of a `401` from the API carries its URL as `resource_metadata`. |

OpenID Connect is not offered: there are no ID tokens and no `/.well-known/openid-configuration`.

## Registering an app

There are three ways to get a `client_id`. An administrator can turn each of them off, so an instance may offer fewer
(the metadata shows which are on). Prefer them in this order.

### 1. Client ID Metadata Document (preferred)

Use this for apps you distribute: a mobile app, a CLI, a web client. There is nothing to register. The `client_id` is an `https` URL
that serves a JSON document describing the app, and the server fetches it when the app starts an authorization.
It works on every instance that has the feature on, with no per-instance setup.
This is an IETF working-group draft
([draft-ietf-oauth-client-id-metadata-document](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/)), not an RFC.

```json
{
  "client_id": "https://app.example/oauth/client.json",
  "client_name": "Example",
  "client_uri": "https://app.example/",
  "logo_uri": "https://app.example/logo.png",
  "redirect_uris": ["https://app.example/oauth/callback", "com.example.app:/oauth/callback", "http://127.0.0.1/callback"],
  "scope": "read write:statuses"
}
```

- `client_id` must equal the URL of the document exactly. The URL is `https`, has a path, and has no fragment, userinfo, or `.` / `..` segment; at most 2048 bytes.
- `redirect_uris` is required: 1 to 20 URIs, each of a form allowed by [Redirect URIs](#redirect-uris-and-native-apps).
- `client_name` (at most 200 characters; the host of the `client_id` when absent), `client_uri` and `logo_uri` (used only when `https`) are shown on the consent screen.
- `scope` is the most the app may ask for. Unknown scopes and [first-party-only scopes](#scopes) are dropped. When absent, it is every scope a third party may hold.
- `grant_types`, `response_types` and `token_endpoint_auth_method`, when present, must allow the authorization code grant and `none`.
  The document must not contain `client_secret`: these clients are public and use PKCE.
- Serve the document with a successful response and without redirects (the server does not follow them), at most 5 KB, with ordinary HTTP caching headers.
  The server reuses it for what the response allows (an hour when it says nothing, and at most 24 hours), does not cache failures, and fetches through an SSRF-guarded client.
  A fetch that fails makes the authorization request fail as an unknown client.
- An administrator can deny a host; a denied host's documents are no longer fetched and the tokens of its clients stop working.

### 2. Registration by a user

Use this for a bot, an integration, or a script that you run yourself. A signed-in user registers the app in **Settings → Apps → Your apps**
(or with `POST /api/v1/oauth_apps`, scope `write:accounts`): a name, the site URL, redirect URIs, the most scope the app may ask for, and the type.

- A **public** app has no secret. A **confidential** app gets a `client_secret`, shown **once**, when the app is registered or its secret reissued (`POST /api/v1/oauth_apps/{id}/rotate_secret`);
  reissuing invalidates the old secret at once. Only a hash is stored.
- A confidential client authenticates at the token endpoint with `client_secret_basic` or `client_secret_post`. **PKCE is required for it too.**
- The owner can edit and delete the app. A user keeps at most 25 apps, and registering is rate limited.
- **Tokens for yourself:** a registered app can issue an access token and a refresh token for its owner's own account from the settings page (`POST /api/v1/oauth_apps/{id}/tokens`),
  with no redirect and no consent screen. Choose the scopes there. They are ordinary tokens with the lifetimes below. A bot stores the rotated refresh token each time it refreshes.
  Only these tokens may hold a [permission scope](#permission-scopes), which lets a service outside the server call the administration operations of one permission.
- An instance can turn off registration by users (the setting `user_app_registration`); apps already registered keep working.

### 3. Dynamic client registration (RFC 7591)

Use this for a generic tool that cannot publish a metadata document. `POST /oauth/register` takes no authentication and a JSON body:

```sh
curl -X POST https://my.example/oauth/register \
  -H 'Content-Type: application/json' \
  -d '{"client_name":"Example","redirect_uris":["http://127.0.0.1/callback"],"scope":"read"}'
```

- The body is a single JSON object of at most 16 KiB; anything after the object, or a larger body, is rejected with `invalid_client_metadata`.
- Only **public clients**. `token_endpoint_auth_method` defaults to `none`; any other value is rejected with `invalid_client_metadata`.
- Accepted metadata: `client_name`, `client_uri`, `logo_uri`, `redirect_uris`, `scope`, `grant_types`, `response_types`. A `software_statement` is not accepted.
  `scope` is narrowed to what a third party may hold; the response states the scope that was granted.
- The answer is `201` with `client_id`, `client_id_issued_at` and the registered metadata. There is no `client_secret` and no registration access token:
  RFC 7592 (reading, updating, deleting a registration) is not supported. To change an app, register again.
- CORS allows any origin, because the endpoint takes no credentials. It answers `403` (`access_denied`) when registration is turned off.
- A client that never exchanges an authorization code within a day (by default), or has had no usable token and no use for 90 days (by default), is deleted by a periodic job.
  Register again if your `client_id` stops working (`dynamic_client_unredeemed_retention` and `dynamic_client_idle_retention` in the [configuration reference](https://mycroblog.dev/next/reference/configuration/)).

## Authorization

The server supports the authorization code grant ([RFC 6749](https://www.rfc-editor.org/rfc/rfc6749) §4.1) and the refresh token grant.
There is no `client_credentials` (every operation is done as a user; authorize a bot as the user of its bot account), no password, implicit, or device grant.

1. Generate a `code_verifier` and its `S256` `code_challenge` ([RFC 7636](https://www.rfc-editor.org/rfc/rfc7636)). **PKCE with `S256` is required for every client.** `plain` is refused.
2. Send the user's browser to `GET /oauth/authorize` with `response_type=code`, `client_id`, `redirect_uri`, `code_challenge`, `code_challenge_method=S256`, `scope` (space-separated) and `state`.
   `redirect_uri` is required and must match one of the app's registered URIs exactly (a loopback URI ignores the port).
   Scopes beyond the app's, a first-party-only scope, or a [permission scope](#permission-scopes), are refused with `invalid_scope` rather than dropped.
   Without `scope`, the request asks for the app's scopes without its permission scopes.
3. The user signs in if needed and sees the **consent screen**. It is shown on every authorization; consent is not remembered.
   It names the app, where it comes from, the site, the scopes in words, and the host of the redirect URI.
   Every third-party app is labelled as one the server has not verified: the name and logo are the app's own claim; only the host of a `client_id` URL or the registering user is verified.
   An app that redirects to a private-use scheme or loopback address gets an extra warning, because another app could claim the same address.
4. The browser is redirected (`303`) to `redirect_uri` with `code`, `state` and `iss` (the server's origin, [RFC 9207](https://www.rfc-editor.org/rfc/rfc9207): check it).
   The code is single use and valid for 60 seconds.
5. `POST /oauth/token` (form-encoded) with `grant_type=authorization_code`, `code`, `redirect_uri`, `client_id`, `code_verifier`
   (and the client secret for a confidential client) returns `access_token`, `refresh_token`, `token_type: Bearer`, `expires_in` and `scope`.
6. Call the API with `Authorization: Bearer <access_token>`. Cookies and query strings never authenticate.

### Tokens

| | Lifetime | Notes |
| --- | --- | --- |
| Authorization code | 60 seconds | Single use. |
| Access token (`my_at_...`) | 1 hour | |
| Refresh token (`my_rt_...`) | 30 days | **Rotated on every use**: each `refresh_token` grant returns a new access token and a new refresh token, and the old ones stop working. |

- Always store the newest refresh token. Presenting a refresh token that was already used (or revoked) **revokes the whole token family**, so serialize refreshes
  and do not send two at once; the user has to authorize again.
- `POST /oauth/revoke` ([RFC 7009](https://www.rfc-editor.org/rfc/rfc7009)) revokes a token and its whole family.
- A user can list and revoke authorized apps in the settings of the first-party web client. An administrator can disable an app (and deny a metadata document host):
  its tokens stop working at once and the app cannot be authorized.
- A `401` carries `WWW-Authenticate: Bearer` with `error="invalid_token"` when the token is not valid; refresh it, or authorize again when that fails.

### Redirect URIs and native apps

Redirect URIs follow [RFC 8252](https://www.rfc-editor.org/rfc/rfc8252) and are matched exactly against the registered ones. Allowed:

| Form | Example | Notes |
| --- | --- | --- |
| Claimed `https` (Universal Links / App Links) | `https://app.example/oauth/callback` | Recommended: the OS verifies that the app owns the domain, so no other app can take the redirect. |
| Private-use URI scheme | `com.example.app:/oauth/callback` | The scheme must be in reverse domain notation. Common web schemes (`http`, `javascript`, `data`, `file`, ...) are refused. The OS does not verify who owns a scheme. |
| Loopback | `http://127.0.0.1/callback`, `http://[::1]/callback` | The port is ignored when matching, so a CLI can listen on any free port. `localhost` is not accepted; use the IP literal. |

`urn:ietf:wg:oauth:2.0:oob`, fragments, and userinfo are refused.

For apps with a `client_id` URL or a dynamic registration, a private-use scheme or loopback address cannot prove who the app is,
so the consent screen warns the user about it. Prefer a claimed `https` redirect for an app that has one.

## Scopes

Scopes are the same as the first-party web client's, in two levels: broad scopes (`read`, `write`, `follow`, `push`) that grant the fine-grained ones under them
(`read:statuses`, `write:statuses`, ...). Each operation in the OpenAPI document lists the scopes it needs; an app may ask for either level.
The list the instance offers is `scopes_supported` in the [authorization server metadata](#discovery).
A request without enough scope gets `403` with `WWW-Authenticate: Bearer error="insufficient_scope"`.

- **Direct messages:** reading posts of the `direct` visibility needs `read:direct` (the broad `read` includes it). A token with only `read:statuses` never receives a `direct` post in a timeline, thread, notification, bookmark or favourite list, post source, or list of quotes, the user's own posts included.
  Sending a direct post needs only `write:statuses`. A token without `read:direct` cannot favourite, bookmark, boost, react to, or vote on a `direct` post: it gets `404` and nothing changes. It can still take back what the user already had on one, such as a favourite: that takes effect and the answer is the same `404`, which shows nothing of the post.
- **Voice chat rooms:** opening a room with a start post (`post`) publishes a post, so it needs `write:statuses` besides `write:voice`; without it the request gets `403` `/api/v1/problems/insufficient-scope`.
- **Reading through a write scope:** a write scope reads the post it acts on, because the response to an action on a post (favouriting it with `write:favourites`, for example) is the whole post, followers-only content included.
- **First-party-only scopes:** `admin`, `admin:read`, `admin:write` and `write:supporters` are never granted to a third-party app,
  not even through `write`. Asking for one at the authorization endpoint is an `invalid_scope` error. Administration is done from the first-party web client,
  or with a [permission scope](#permission-scopes) on a token that the user issues to themselves.
- **First-party-only operations:** the operations below are marked `x-first-party-only` in the OpenAPI document and answer a third-party token with `403` `/api/v1/problems/first-party-only`, whatever its scopes.
  - Account security: password, two-factor authentication, passkeys, deleting the account, the list of signed-in browsers, and the list of authorized apps.
  - Data exports, including the CSV exports, and data imports. Read the posts and lists an app needs through their own scopes instead.
  - Changing and previewing the automatic deletion of posts. Reading the policy stays under `read:accounts`.
  - Adding and removing aliases, which consent to another account moving its followers here. Reading them stays under `read:accounts`.
  - Listing, creating, and revoking the user's own invites (`listOwnInvites`, `createOwnInvite`, `revokeOwnInvite`). The staff's invites are administration operations.
  - The user's list of moderation actions, and appeals.
- **Moderator notifications:** a third-party token never gets the moderator notifications (`admin_report`, `admin_appeal`, `admin_sign_up`, and the like), whatever the user's roles. They are left out of the notification list, the stream, and the unread count of the marker, and they are dropped from the alerts of the app's Web Push subscription.
- **Relationships:** a `Relationship` holds only the fields of the lists the token's scopes cover, and the others are absent. `following`, `requested`, `followed_by`, `requested_by`, `show_boosts`, and `notify` need `read:follows` or `write:follows`; `blocking` needs `read:blocks` or `write:blocks`; `muting` and `muting_notifications` need `read:mutes` or `write:mutes`. An absent field says nothing about the state, so do not read it as false.

### Permission scopes

A permission scope is `admin:` and the name of a permission of the user's roles: `admin:manage_invites`, `admin:manage_finance`, and so on.
It lets a service outside the server, such as one that hands out invites or records costs, call the administration operations of that permission and nothing else.

- **Which operations:** each administration operation names the permission it needs with `x-permission` in the OpenAPI document. A token with that permission's scope may call it in place of `admin:read` or `admin:write`.
  An operation without `x-permission`, or one that needs another permission, answers `403` `/api/v1/problems/insufficient-scope`.
  A webhook such a token sets up may subscribe only to the events that its permission scopes show.
- **The roles still decide:** every call needs the permission on the user's roles, as for the web client. A token whose user loses the permission gets `403` `/api/v1/problems/missing-permission`.
- **Only for yourself:** only a [token you issue to yourself](#2-registration-by-a-user) may hold a permission scope, and only for a permission your roles hold when you issue it. Add the scope to the app's scopes first.
  No authorization request may ask for one, so a consent screen never asks a staff member for administration.
- **Which permissions:** every moderation and server administration permission has one, except `manage_roles`, `manage_oauth_apps`, `manage_login_recovery`, `manage_login_providers`, and `manage_service_closure`. The member permissions have none.
  `scopes_supported` does not list them, because no authorization request may ask for them.
- **Give a service its own account:** sign up an account for the service, give it a role with only the permissions the service needs, register an app with that account, and issue the token from it.
  The service then refreshes the token and stores the new refresh token each time, since the access token lasts one hour.

Next: [paging](https://mycroblog.dev/next/developers/paging/), [errors](https://mycroblog.dev/next/developers/errors/), [rate limits](https://mycroblog.dev/next/developers/rate-limits/), and the [event stream](https://mycroblog.dev/next/developers/streaming/). To skip the plumbing, use the [client libraries](https://mycroblog.dev/next/developers/libraries/).
