# Start an agent authorization (code with PKCE)

> Start an agent authorization (code with PKCE): CustomDomain™ API reference in the agents group. Covers parameters, request body, responses and error codes.

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

## `GET https://api.customdomain.ai/v1/oauth/agent/authorize`

The authorization endpoint. A browser is sent here by an agent; the request is validated (the client, the exact redirect URI, S256 PKCE, the scopes, the resource) and the browser is redirected to the console, where a signed in owner or admin sees what the agent asks for and where its code would go, and approves or denies. The authorization code goes to the redirect URI and is exchanged at `POST /oauth/agent/token`. A request with an unregistered or mismatched redirect URI is refused without redirecting. `client_id` is a registered client or an https URL of a Client ID Metadata Document.

### Authentication

None.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `client_id` | query | string | yes |  |
| `redirect_uri` | query | string | yes |  |
| `response_type` | query | `code` | yes |  |
| `code_challenge` | query | string | yes | BASE64URL(SHA-256(code_verifier)). |
| `code_challenge_method` | query | `S256` | yes |  |
| `scope` | query | string | yes | Space separated scopes from `domains:read`, `domains:connect`, `domains:disconnect` and `domains:purchase`, and the workspace scopes `stats:read`, `audit:read`, `app:read`, `app:write`, `tokens:mint`, `member:read`, `member:manage` and `keys:manage`. The person may approve fewer, and can grant a workspace scope only if their own role holds it. |
| `state` | query | string | no |  |
| `resource` | query | string | no | RFC 8707. The resource the token is for: the MCP endpoint (`https://mcp.customdomain.ai/mcp`, the default) or this API's origin. Anything else is `invalid_target`. The access token carries it as `aud`. |

### Responses

| Status | Description |
| --- | --- |
| `302` | Redirect to the console consent screen |
| `400` | Error envelope: {code, title, details}. |
| `503` | Error envelope: {code, title, details}. |

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