Skip to main content
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 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

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. 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.