OAuth 2.1
Let other apps sign in their users with a Bot-Hosting account, like Sign in with Discord. Built on OAuth 2.1 and PKCE, so any standard OAuth client works.
Use an API key to drive your own account. Use OAuth when you build an app that acts on other people's accounts, so they log in and consent instead of pasting a key. AI assistants like ChatGPT connect through this exact flow.
The flow
- 01 Create an app Register a name and a redirect URI in your developer settings. You get a public client_id, with no secret.
- 02 Send users to authorize Redirect to /oauth/authorize with PKCE. The user logs in and approves the scopes.
- 03 Exchange the code They come back with a code. POST it to the token endpoint for an access token.
- 04 Call the API as them Send the token as a Bearer to /api/v1, and refresh it in the background.
Endpoints
| Endpoints | Purpose |
|---|---|
| GET /oauth/authorize | User consent screen, opened in the browser. |
| POST /api/oauth/token | Exchange a code for a token, or refresh one. |
| POST /api/oauth/register | Dynamic Client Registration (RFC 7591), optional. |
| GET /.well-known/oauth-authorization-server | Discovery metadata. |
| GET /.well-known/oauth-protected-resource | Resource metadata, used by MCP clients. |
Token lifetimes
Authorization code 10 min Single-use, bound to PKCE.
Access token 7 days Bearer for /api/v1 calls.
Refresh token 30 days Rotated on every use.
Refresh
Every refresh returns a new refresh token and revokes the old one: always overwrite the stored one. If a refresh returns invalid_grant, send the user back through step 1.
Security
- Store tokens server-side, tied to your user. Never ship them to the browser or a public repository.
- Tokens are revoked the moment the user disconnects your app.
- Use https redirect URIs in production. http is accepted for local testing.
- OAuth tokens never grant admin, whatever scopes are approved.