OAuth

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

Preview. OAuth is available to organisations in the Wordsmith MCP and files pilot. See the preview overview.

An API key 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 [e-mail] 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.

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.