> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apostra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Verify operator domain

> Optionally add AAO or manual evidence to a confirmed buyer operator identity

Domain verification is optional evidence; it does not block buying. The
required account identity is the operator domain plus an explicit choice of
whole operator or specific operating unit. An account administrator confirms
that identity in Buyer Setup or with
`PATCH /api/v2/buyer/readiness/operator` before using either verification path.

Two endpoints can then add verification evidence without changing the account
scope, operating-unit ID, organization membership, or billing company.

## Verify via AAO

`POST /api/v2/buyer/readiness/operator/verify`

Verifies the operator domain by checking the email claim in an AdCP Alliance Organization (AAO) identity token. Use this path when your work email domain matches the domain you're claiming.

The caller must have already completed the AAO OAuth flow (using `openid email` scopes). Pass the resulting `id_token` alongside the domain to verify. The server verifies the JWT signature against AAO's public keys and compares the email domain to the claimed operator domain. On a match, the domain is marked verified for the account.

```bash curl theme={null}
curl -X POST https://api.apostra.com/api/v2/buyer/readiness/operator/verify \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "acmeretail.com",
    "idToken": "<id_token from AAO OAuth>",
    "audience": "<client_id from AAO dynamic client registration>"
  }'
```

### Parameters

| Field      | In   | Type   | Required | Notes                                                                                        |
| ---------- | ---- | ------ | -------- | -------------------------------------------------------------------------------------------- |
| `domain`   | body | string | Yes      | Operator domain to verify (hostname, no `https://` prefix)                                   |
| `idToken`  | body | string | Yes      | JWT `id_token` returned by the AAO OAuth token endpoint                                      |
| `audience` | body | string | Yes      | `client_id` returned by AAO dynamic client registration. Prevents cross-session token reuse. |

### Response

```json theme={null}
{ "verified": true }
```

### Errors

* `400 VALIDATION_ERROR` — missing or malformed `domain` or `idToken`; or the email claim in the `id_token` does not match the claimed domain (the error context includes `aaoEmailDomain`). Use the [manual review path](#request-manual-review) if your email is from a different organization.
* `401 UNAUTHORIZED` — missing or invalid bearer token.
* `404 NOT_FOUND` — no saved operator identity exists for this account. Confirm it first with `PATCH /api/v2/buyer/readiness/operator` or in Buyer Setup.
* `500 INTERNAL_ERROR` — the `id_token` could not be verified (invalid signature, expired, or AAO metadata unavailable). Retry the OAuth flow.

***

## Request manual review

`POST /api/v2/buyer/readiness/operator/verify-request`

Submits a manual verification request. Use this path when you're an agency or consultant claiming a client domain that doesn't match your work email. Your request has been recorded. A member of Apostra team will follow up with you at the email address you provided.

```bash curl theme={null}
curl -X POST https://api.apostra.com/api/v2/buyer/readiness/operator/verify-request \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "clientbrand.com",
    "requesterEmail": "you@youragency.com",
    "message": "We are the agency of record for this brand."
  }'
```

### Parameters

| Field            | In   | Type   | Required | Notes                                   |
| ---------------- | ---- | ------ | -------- | --------------------------------------- |
| `domain`         | body | string | Yes      | Operator domain to verify               |
| `requesterEmail` | body | string | Yes      | Your contact email for this request     |
| `message`        | body | string | No       | Brief explanation (max 2000 characters) |

### Response

Returns `202 Accepted`:

```json theme={null}
{ "submitted": true, "id": "12345" }
```

### Errors

* `400 VALIDATION_ERROR` — missing or malformed fields.
* `401 UNAUTHORIZED` — missing or invalid bearer token.

***

## Related

<CardGroup cols={2}>
  <Card title="Buyer setup and go-live" href="/v2/buyer/account/setup" icon="globe">
    Confirm the operator domain, account scope, and stable operating-unit ID
    before adding optional verification evidence.
  </Card>

  <Card title="Account tasks" href="/v2/buyer/account/tasks" icon="list-check">
    All account operations
  </Card>
</CardGroup>