# Approve an agent and mint its authorization code

> Approve an agent and mint its authorization code: CustomDomain™ API reference in the agents group. Covers parameters, request body, responses and error codes.

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

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

Called by the console's server after a person signs in and approves, with that member's tenant API key (a widget token is refused, because it lives in browsers). The key's member needs `agent:manage` (owners and admins), and `member_id` must belong to the workspace. The workspace default key cannot approve (`403`). The approved scopes are a subset of what was requested. The grant is bound to one `application_id` of the workspace. An agent whose code goes to an unverified host needs `acknowledged_unverified: true`, and one whose name imitates a brand is refused (`403`). `domains:purchase` also needs a `spend_cap_cents` and a saved card. Persistent access is the default; `persist: false` ends it after `expires_days`. The authorization code is single use and is exchanged at `POST /oauth/agent/token`.

### Authentication

`apiKey`

### Request body (JSON)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `request` | string | yes | The consent request id the browser arrived with (`aqr_...`). |
| `member_id` | string | no | The member who approves, recorded as the grant's approver, the email recipient and the audit actor. It must belong to the workspace. With a member's own key it must be that member (`403` otherwise) and may be left out. With any other key it is required (`400`) and must name an owner or admin (`403`) who has joined the workspace (`400`). |
| `application_id` | string | yes | The one application of the workspace the agent will act within. |
| `scopes` | array of `domains:read`, `domains:connect`, `domains:disconnect`, `domains:purchase`, `stats:read`, `audit:read`, `app:read`, `app:write`, `tokens:mint`, `member:read`, `member:manage`, `keys:manage` | yes | What is approved, a subset of what the agent asked for. |
| `can_purchase` | boolean | no | Ignored. Purchase is allowed exactly when `domains:purchase` is among the scopes. |
| `spend_cap_cents` | integer | no | The monthly spend cap in US cents. Required, and above 0, with `domains:purchase`, which also needs a saved card (`409` without one). |
| `persist` | boolean | no | True (the default) keeps the access until it is revoked. False ends it after `expires_days`. |
| `expires_days` | integer | no | With `persist: false`, days until the grant expires. |
| `acknowledged_unverified` | boolean | no | The approver confirmed they recognize the host the authorization code goes to. Required (`true`) when that host is neither a known assistant's (`verified`) nor a loopback address (`local`) in `GET /agent/consent-request/{id}`; without it such a consent is refused with `400`. |

### Responses

| Status | Description |
| --- | --- |
| `200` | The redirect for the agent, with its code |
| `400` | Error envelope: {code, title, details}. |
| `401` | Error envelope: {code, title, details}. |
| `403` | Error envelope: {code, title, details}. |
| `409` | Error envelope: {code, title, details}. |
| `503` | Error envelope: {code, title, details}. |

### `200` response body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `redirect_uri` | string | yes | Where to send the person: the agent's redirect URI with `code` and `state` added. |
| `code` | string | yes | The single use authorization code. It lives 5 minutes. |
| `state` | string | no |  |
| `grant_id` | string | yes | The id the grant has once the agent exchanges the code. Until then the grant is not listed. |

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