Agent OAuth
Agent OAuth
OAuth authorization server endpoints that MCP clients use to sign in and receive tokens
Overview
The Agent OAuth endpoints let an MCP client, such as Claude, Cursor, or ChatGPT, sign in to Doxa on behalf of a user. The client reads the server metadata, registers itself, sends the user to the consent page, and then exchanges the authorization result for access and refresh tokens. The MCP server uses those tokens to decide which tools a connected agent can run.
This group has four endpoints. Most readers never call them directly, because the MCP client runs the sign-in flow when you add the Doxa server. Use this reference if you build a custom MCP client or need to understand how sign-in works.
Discovery: read the authorization server metadata.
Authorization: start sign-in. The user picks scopes and projects on the consent page.
Token: exchange the authorization result for tokens, or refresh them.
Registration: register the MCP client before sign-in.
Schema
The sign-in flow uses the following values. Token field names follow the standard OAuth 2.0 response.
| Field | Type | Required | Description |
|---|---|---|---|
access_token | string | Yes (token response) | Bearer token that the MCP server checks on each request. Valid for 1 hour. |
refresh_token | string | Yes (token response) | Used to get a new access token. Valid for 30 days, or 14 days without use. |
scope | string | Yes (consent) | Scopes the user granted, such as projects:read or docs:write. |
projects | all or list | Yes (consent) | Projects the agent can access: all projects, or a list the user selects. |
Endpoints
| Method | Path | Description |
|---|---|---|
| GET | /.well-known/oauth-authorization-server | Returns the OAuth authorization server metadata for MCP clients. |
| GET | /oauth/authorize | Starts authorization. Checks the client, stores a pending consent for 10 minutes, and redirects to the consent page. |
| POST | /oauth/token | Issues access and refresh tokens. Also handles token revocation. |
| POST | /oauth/register | Registers an MCP client. |
Note:
A consent is single use. If the user does not complete the consent page within 10 minutes, start the authorization again.
Note:
Access tokens last 1 hour. Refresh tokens last 30 days, or 14 days without use. Users can review and revoke grants under Settings, Connected agents.