> ## Documentation Index
> Fetch the complete documentation index at: https://wordsmithai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# OAuth

> Let users connect an approved app to Wordsmith with OAuth 2.1, instead of sharing an API key.

> [!NOTE]
>
> **Preview.** OAuth is available to organisations in the Wordsmith MCP and files pilot. See the [preview overview](/preview).

An [API key](/authentication) acts with everything its creator can do. OAuth lets a user connect an app with a narrower set of permissions, called scopes. The user signs in to Wordsmith and approves the scopes, and the app receives tokens that expire and renew on their own. MCP hosts such as ChatGPT and Claude use this flow, and so can an app that calls the REST API.

Wordsmith accepts only approved apps. An app is recognised by the redirect URI its authorisation codes are sent to, so a new app has to be added to Wordsmith's allowlist before it can register. Contact [support@wordsmith.ai](mailto:support@wordsmith.ai) to have yours added. Wordsmith can also restrict the list for your organisation on request.

## The flow

Wordsmith follows OAuth 2.1, with dynamic client registration (RFC 7591), PKCE with `S256` only, and resource indicators (RFC 8707).

**1. Discover the endpoints**

`GET https://api.wordsmith.ai/.well-known/oauth-authorization-server` lists every endpoint below. For the REST API, `GET /.well-known/oauth-protected-resource/api/v1` names the resource to request.

**2. Register the app**

`POST /oauth/register` with your `client_name`, `redirect_uris`, and the `scope` you need. Each redirect URI must be on the allowlist. A registration that is never used expires after 30 days.

**3. Send the user to sign in**

Redirect the user to `/oauth/authorize` with `response_type=code`, your `client_id`, `redirect_uri`, `scope`, a `state`, a PKCE `code_challenge` with `code_challenge_method=S256`, and `resource=https://api.wordsmith.ai/api/v1`. The user signs in and approves the scopes on Wordsmith's consent screen.

**4. Exchange the code**

`POST /oauth/token` with `grant_type=authorization_code`, the `code`, your `code_verifier`, and your client credentials. You receive an access token and a refresh token.

**5. Call the API**

Send the access token as `Authorization: Bearer <token>`, exactly like an API key. A call outside the token's scopes returns `403 insufficient_scope`, naming the scope it needs.

**6. Refresh**

`POST /oauth/token` with `grant_type=refresh_token`. Each refresh returns a new refresh token, and the old one stops working. Keep only the newest.

## Tokens

| Token | Lifetime |
| - | - |
| Access token | 1 hour |
| Refresh token | 30 days, renewed on every refresh |
| Whole grant | 60 days from consent. After that the user signs in again. |

Revoke a token with `POST /oauth/revoke`. Revoking a refresh token also ends the access tokens issued from it.

## Scopes

A `:write` scope includes its `:read` scope, except `files:write`.

| Scope | Grants |
| - | - |
| `me:read` | The user's name and email. |
| `agents:read` | List agents. |
| `sessions:read` / `sessions:write` | Read answers / ask agents questions. |
| `tasks:read` / `tasks:write` | Read tasks / create, update and comment on them. |
| Operations | `GET /operations` and `GET /operations/{id}` need the read scope of the operation's type, such as `sessions:read` for a question. Cancelling needs its write scope. |
| `files:read` / `files:write` | Read and download files / upload them. |
| `playbooks:read` | List playbooks. |
| `blueprints:read` | List blueprints. `templates:read`, its old name, still works. |
| `directory:read` | List people and teams. |
| `mcp:access` | Connect to the [MCP server](/mcp-server). |

An app that requests no scope, and registered none, gets every scope in this table. It also gets `mcp:access`, unless it named the REST API as its `resource`. Ask only for what the app needs: the consent screen shows the user each one.

## What OAuth callers cannot do

* **Callbacks.** `callback_url` needs an API key's webhook secret to sign with, so OAuth callers poll for answers instead.
* **Artifacts.** The artifacts routes accept API keys only.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.