# Exchange an authorization code or a refresh token for an access token

> exchange agent token: reference page for this CustomDomain™ API operation in the agents group. Covers parameters, request body, responses and error codes.

Source: https://docs.customdomain.ai/docs/api-reference/agents/exchangeAgentToken

## `POST https://api.customdomain.ai/v1/oauth/agent/token`

`grant_type=authorization_code` (with the PKCE `code_verifier`) or `grant_type=refresh_token`. The access token is an ES256 JWT that lives 15 minutes and is verified locally against `/.well-known/jwks.json`; it carries the tenant, the application the grant is bound to, the grant, the scopes and `aud`. A refresh token rotates: every refresh returns a new one and retires the old, and presenting a retired one again revokes the whole grant (a client racing itself within ten seconds is only refused). Errors use the RFC 6749 envelope.

### Authentication

None.

### Request body (JSON)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `grant_type` | `authorization_code`, `refresh_token` | yes |  |
| `client_id` | string | yes |  |
| `code` | string | no | With `authorization_code`: the single use code from the redirect. It lives 5 minutes. Presenting a code that already issued tokens is `invalid_grant` and revokes the grant they came from (RFC 6749 §4.1.2). |
| `code_verifier` | string | no | With `authorization_code`: the PKCE verifier for the `code_challenge` sent to authorize. |
| `redirect_uri` | string | no | With `authorization_code`: exactly the `redirect_uri` sent to authorize. |
| `refresh_token` | string | no | With `refresh_token`: the latest refresh token. It is good for one exchange. |
| `resource` | object | no | RFC 8707. The resource the token is for. With `authorization_code` it must be the one the person approved; with `refresh_token` it picks the audience of the new access token (the MCP endpoint when omitted). In a form body repeat the field; in JSON send a string or a list. |

### Responses

| Status | Description |
| --- | --- |
| `200` | The tokens |
| `400` | `invalid_request`, `invalid_grant` (a code or refresh token that is invalid, expired, spent or revoked, a failed PKCE check, a grant that is no longer active or whose approver no longer manages agents in the workspace), `invalid_target` (a resource that is not the one approved) or `unsupported_grant_type`. |
| `503` | `temporarily_unavailable`: agent access is not enabled on this deployment, or the grant could not be checked; retry later. |

### `200` response body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `access_token` | string | yes | An ES256 JWT. Verify it against `/.well-known/jwks.json`. |
| `token_type` | `Bearer` | yes |  |
| `expires_in` | integer | yes | Seconds the access token lives (900). |
| `refresh_token` | string | no | A new refresh token. The one just used no longer works. |
| `scope` | string | no | The scopes the grant carries, separated by spaces. |

The full specification is served at `GET https://api.customdomain.ai/v1/openapi.json`.
