> Markdown version of https://authpi.com/docs/reference/core-api/account-domains/ — fetch the complete AuthPI docs index at https://authpi.com/llms.txt to discover all available pages.

# Account Domains — AuthPI Core API

Custom domain management for an account: add, verify, and remove domains used for white-labeled portals and issuers.

## GET /v1/accounts/{account_id}/domains

**List Account Domains**

List all custom domains for an account, including their verification and assignment status.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Domains retrieved successfully | `object` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |

## POST /v1/accounts/{account_id}/domains

**Add Account Domain**

Add a custom domain to the account.

The domain is added in an unverified state. Verification will happen via Cloudflare Custom Hostnames when the domain is assigned to an issuer (Phase 2).

**Limits:** Maximum 20 domains per account.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |

### Request body

Content type: `application/json`

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `host` | string | Required | Domain name (e.g., 'auth.example.com') |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 201 | Domain added successfully | `object` |
| 400 | **Bad Request** - The request is malformed or contains invalid data. | `ApiError` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |
| 409 | **Conflict** - The request conflicts with the current state of the resource. | `ApiError` |

## DELETE /v1/accounts/{account_id}/domains/{domain}

**Remove Account Domain**

Remove a custom domain from the account.

If the domain is assigned to an issuer, the assignment and global routing index are cleaned up automatically.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `domain` | string | Required | Domain name (e.g., 'auth.example.com') |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 204 | **No Content** - The operation completed successfully with no response body. | — |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |

## POST /v1/accounts/{account_id}/domains/{domain}/verify

**Verify Account Domain**

Mark a domain as verified.

In Phase 2, this will be called automatically when Cloudflare confirms the Custom Hostname is active. For now, it can be called manually (e.g., by an admin) after verifying ownership.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `domain` | string | Required | Domain name (e.g., 'auth.example.com') |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Domain verified successfully | `object` |
| 400 | **Bad Request** - The request is malformed or contains invalid data. | `ApiError` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |

## POST /v1/accounts/{account_id}/domains/{domain}/assign

**Assign Domain to Issuer**

Assign a verified domain to an issuer owned by this account.

Once assigned, the IDP portal will route traffic for this domain to the specified issuer. A global KV index is written for fast domain-to-issuer lookups at the edge.

**Requirements:**
- Domain must be verified
- Issuer must belong to the same account
- A domain can only be assigned to one issuer at a time (reassignment is allowed)

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `domain` | string | Required | Domain name (e.g., 'auth.example.com') |

### Request body

Content type: `application/json`

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `issuer_id` | string | Required | The issuer ID to assign this domain to |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Domain assigned to issuer successfully | `object` |
| 400 | **Bad Request** - The request is malformed or contains invalid data. | `ApiError` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |

## POST /v1/accounts/{account_id}/domains/{domain}/unassign

**Unassign Domain from Issuer**

Remove the issuer assignment from a domain.

The domain remains on the account but is no longer routed to any issuer. The global KV index entry is removed.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `domain` | string | Required | Domain name (e.g., 'auth.example.com') |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Domain unassigned successfully | `object` |
| 400 | **Bad Request** - The request is malformed or contains invalid data. | `ApiError` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |