> ## 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.

# Sign in a self-built agent

> How an agent you build signs in to Apostra with OAuth: discovery, client registration, redirect URIs, tokens, browser use, and the errors you can hit. Also how an agent with no person present registers itself.

If you build your own agent and a person is there to approve it, you do not ask
Apostra for access first. Point an MCP client at the endpoint, let it sign in,
and the person approves it on a consent screen. No account admin approves your
agent, and no allowlist needs your domain or origin on it.

If nobody is there to click, skip to [Agents with no person present](https://docs.apostra.com/v3/agent-sign-in.md#agents-with-no-person-present).

## The short path

Point an MCP SDK client at `https://api.apostra.com/mcp/v3`. A client that
supports MCP authorization does the rest:

1. It calls the endpoint without a token and gets `401`. The
   `WWW-Authenticate` header carries a `resource_metadata` URL.
2. It reads that metadata to find Apostra's authorization server, then reads
   `/.well-known/oauth-authorization-server` for the endpoints, including
   `registration_endpoint` and `client_id_metadata_document_supported: true`.
3. It identifies itself, with a [Client ID Metadata Document](https://docs.apostra.com/v3/agent-sign-in.md#client-id-metadata-documents)
   or by [registering](https://docs.apostra.com/v3/agent-sign-in.md#dynamic-client-registration).
4. It opens a browser. The person signs in to Apostra, then approves or denies
   your agent on the consent screen.
5. The browser returns to your agent's redirect URI with an authorization
   code. The client exchanges it, with a PKCE verifier, for an access token and
   a refresh token.

Then your agent calls the endpoint with `Authorization: Bearer <access token>`.
Call `get_status` first to confirm which account the person signed in as.

An MCP SDK client does all of this when you give it a redirect URI and a place to
store tokens. Read the OAuth section of the SDK you use. The rest of this page
is for when you write the flow yourself, or when something fails.

## What the person sees

Apostra asks every time an agent authorizes, including when the person is
already signed in. The consent screen shows:

| Shown | What it is | Why it matters |
| - | - | - |
| The agent's name | The `client_name` your agent registered, or the name in its metadata document | Your agent chooses this name, so it is not proof of anything. For an agent that registered itself through `/auth/register`, the heading names the "Returns you to" address instead, and the name appears below it labeled as chosen by the app and not verified |
| Returns you to | The address the browser goes to after the decision: the redirect URI's origin, or its scheme and host for a custom scheme | This is the part the person can check. A code only ever goes to a redirect URI your client declared |
| App published by | The domain of your metadata document URL. Shown only for [Client ID Metadata Document](https://docs.apostra.com/v3/agent-sign-in.md#client-id-metadata-documents) clients | Apostra fetched your document from that domain, so the domain vouches for the name and redirect URIs |
| Access to | The MCP endpoint the agent is asking for, such as `https://api.apostra.com/mcp/v3` | The grant works on that one endpoint only |
| Scopes and Account | Only when the agent asks for the HTTP API (`https://api.apostra.com/api/v3`): the access it asks for, and a list of your accounts to choose from | The token works for the one account you choose. See [Sign in to the HTTP API](https://docs.apostra.com/v3/agent-sign-in.md#sign-in-to-the-http-api) |
| Signed in as | The Apostra account email | The agent acts as this person, with their permissions |

That screen is the trust anchor. The person, not an admin, decides whether this
agent may act as them. **Approve** issues the code. **Deny** sends the browser to
your redirect URI with `error=access_denied` and issues nothing. The decision is
tied to a one-time session that lasts 10 minutes.

## Register your agent

Your agent identifies itself to Apostra in one of two ways. Both create a public
client: no client secret, with PKCE doing the proof. Use one or the other.

### Client ID Metadata Documents

A Client ID Metadata Document is a JSON file on your own domain. Your `client_id`
is the URL of that file. Nothing is registered ahead of time, and Apostra fetches
the file when a person starts authorizing. The MCP specification (2026-07-28)
prefers this method, and Apostra advertises support with
`client_id_metadata_document_supported: true`, so clients that prefer it use it
without being told.

```json theme={null}
{
  "client_id": "https://agent.example.com/oauth/client.json",
  "client_name": "Example Agent",
  "client_uri": "https://agent.example.com",
  "redirect_uris": ["https://agent.example.com/oauth/callback"],
  "token_endpoint_auth_method": "none"
}
```

Send the file's URL as `client_id` when you start OAuth. Requirements:

* The URL uses `https`, has a path beyond `/`, and has no fragment, username,
  password, or `.` or `..` path segments. It must already be in canonical form:
  lowercase host, no default port.
* `client_id` in the file equals the URL exactly.
* `redirect_uris` is required and each one follows the
  [redirect URI rules](https://docs.apostra.com/v3/agent-sign-in.md#redirect-uri-rules). The `redirect_uri` you send to
  `/authorize` must match one of them exactly, character for character. A
  metadata document gets no loopback port allowance or subpath allowance. The
  one exception is Apostra's own
  [command-line client](https://docs.apostra.com/v3/agent-sign-in.md#the-apostra-command-line-client).
* The file is public. Leave `token_endpoint_auth_method` out or set it to
  `none`. A `client_secret` makes the document invalid.
* Serve it with status `200`, a JSON content type, and a body of at most 5 KB.
  Apostra does not follow redirects, connects only to public internet
  addresses, and gives up after a few seconds.
* Apostra caches a valid file for as long as your `Cache-Control: max-age` says,
  between 1 minute and 24 hours, and 5 minutes when you set none. `no-store` and
  `no-cache` count as the 1-minute minimum. It remembers a failed lookup for
  about a minute. A change to `redirect_uris` takes effect when the cached copy
  expires.

### Dynamic client registration

Dynamic client registration is a `POST` to `/auth/register`. Use it when you
cannot host a public file, for example a desktop tool or a local development
agent.

```bash theme={null}
curl -X POST https://api.apostra.com/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "Example Agent",
    "redirect_uris": ["https://agent.example.com/oauth/callback"]
  }'
```

The `201` response carries a generated `client_id` that starts with
`mcp_client_`, plus the redirect URIs you sent. Do not treat it as a secret.
Notes:

* Always send `redirect_uris`. A request without them returns a shared,
  preconfigured client that is not yours.
* Send up to 25 redirect URIs of at most 2048 characters each. `client_name` is
  at most 120 characters. Apostra removes control, bidirectional-override and
  zero-width characters from it and collapses runs of whitespace, so the name
  reads as it renders; the same applies to the name in a metadata document.
  `client_uri` and `logo_uri`, if you send them, must be `https` URLs.
* A registration you never use to start an authorization is deleted after 24
  hours. A registration unused for 90 days is deleted too. Register again when
  you see [`redirect_uri is not allowed`](https://docs.apostra.com/v3/agent-sign-in#troubleshooting) for a client that
  used to work.

### The Apostra command-line client

Apostra's own command-line tool is a first-party client with a metadata document
that Apostra serves itself, at `https://api.apostra.com/oauth/clients/apostra-cli.json`.
Its `client_id` is that URL, it is a public client (`token_endpoint_auth_method: none`),
and it registers one redirect URI, `http://127.0.0.1/callback`.

A command-line tool cannot know its port ahead of time, so for this client alone
Apostra applies the loopback rule of RFC 8252 section 7.3. The `redirect_uri` you
send may use any port, as long as it keeps:

* the scheme `http`,
* the host `127.0.0.1`, the IP address and not `localhost` or `[::1]`, and
* the path `/callback`, exactly, with no query string.

`http://127.0.0.1:53999/callback` is accepted. `http://localhost:53999/callback`,
`http://127.0.0.1:53999/other` and `http://127.0.0.1:53999/callback?x=1` are
refused. No other client gets this allowance: a client you register, or a
metadata document you host, still has to match its redirect URIs as described
above.

The command-line tool and the SDK helpers that sign in with it ship separately
from the API, in a later release. The API accepts this client today, so you can
follow [Sign in to the HTTP API](https://docs.apostra.com/v3/agent-sign-in.md#sign-in-to-the-http-api) with it
yourself.

## Redirect URI rules

Both registration methods use the same rules for each redirect URI:

* **Web agents:** `https` on any host.
* **Local tools:** `http://localhost`, `http://127.0.0.1` or `http://[::1]`,
  with or without a port. No other `http` address is accepted.
* **Desktop and mobile apps:** a private-use scheme, such as
  `cursor://anysphere.cursor-mcp/oauth/callback` or
  `com.example.agent:/oauth/callback`. The scheme is a letter followed by
  letters, digits, `+`, `-` or `.`, at least two characters long, and something
  must follow it (a host or a path beyond `/`). These schemes are refused:
  `http` (other than loopback), `javascript`, `data`, `file`, `blob`,
  `vbscript`, `about`, `filesystem`, `ws`, `wss` and `ftp`.
* **Never:** a fragment (`#...`) or embedded credentials (`user:pass@`). A URI is
  at most 2048 characters.

The `redirect_uri` you send to `/authorize` and to `/auth/token` must match a
registered URI exactly. The one exception is a client registered with dynamic
registration and a `localhost` or `127.0.0.1` redirect: the request may use the
same host and port with a deeper path (registered `http://localhost:8123/cb`
accepts `http://localhost:8123/cb/done`), as long as neither has a query string.
The port must still match. `http://[::1]` and custom schemes match exactly.

## Tokens and PKCE

PKCE is required, with the `S256` method only. Send `code_challenge` (43 to 128
base64url characters) and `code_challenge_method=S256` to `/authorize`, then the
matching `code_verifier` to `/auth/token`. `plain` is refused.

```text theme={null}
GET https://api.apostra.com/authorize
  ?response_type=code
  &client_id=<your client_id>
  &redirect_uri=<exact redirect URI>
  &code_challenge=<S256 challenge>
  &code_challenge_method=S256
  &resource=https://api.apostra.com/mcp/v3
  &state=<opaque value>
```

Always send `resource`. It names the MCP endpoint the token is for, and it must
be the endpoint's exact URL, with no query or fragment. If you leave it out, the
grant is for the bare `/mcp` endpoint. Apostra accepts a `/mcp` grant at
`/mcp/v3` too, but at no other endpoint, so send the URL you will call.

The browser comes back to your redirect URI with `code`, `state` and `iss` (the
issuer, `https://api.apostra.com`). Check `state`, and check `iss` if your OAuth
library supports it: Apostra advertises
`authorization_response_iss_parameter_supported`. The code works once and expires
after 10 minutes. Exchange it. `/auth/token` accepts form-encoded or JSON bodies.

```bash theme={null}
curl -X POST https://api.apostra.com/auth/token \
  -d grant_type=authorization_code \
  -d code=<code> \
  -d code_verifier=<verifier> \
  -d client_id=<your client_id> \
  -d redirect_uri=<exact redirect URI> \
  -d resource=https://api.apostra.com/mcp/v3
```

The response is a standard token response with `token_type: Bearer`, scope
`mcp:access`, and:

| Token | Lifetime | Notes |
| - | - | - |
| Access token (`mcp_at_...`) | 1 hour (`expires_in: 3600`) | Opaque, not a JWT. Send it as a bearer token |
| Refresh token (`mcp_rt_...`) | 30 days | Rotates on every use |

Both tokens are bound to the person, your client, and the exact `resource`.
Refresh before the access token expires:

```bash theme={null}
curl -X POST https://api.apostra.com/auth/token \
  -d grant_type=refresh_token \
  -d refresh_token=<refresh token> \
  -d client_id=<your client_id> \
  -d resource=https://api.apostra.com/mcp/v3
```

Each refresh returns a new access token and a new refresh token, with a fresh 30
days. Save the new refresh token and discard the old one. Apostra tolerates
concurrent callers that present the same refresh token within 90 seconds of its
rotation (they get the same new pair), so two parallel workers do not break the
grant. Presenting an already-used refresh token after that is treated as theft,
and Apostra ends the whole grant. Use a lock around refresh, or keep one refresher.

### What ends a grant

A grant lasts until one of these happens:

* **Your agent calls the revocation endpoint.** `POST /auth/revoke` with `token`
  set to the access or refresh token (form-encoded or JSON) ends the whole grant.
  Send `client_id` too. A `client_id` that does not match the token's client is
  silently ignored, and the grant stays live. The endpoint returns `200` for
  tokens it does not recognize, and `400` only when `token` is missing.
* **The person disconnects one of your agent's sign-ins** from **Connected apps**
  in their account menu. Both tokens of that grant stop working immediately,
  and your agent has to send the person through sign-in again to come back.
* **The refresh token goes 30 days without use.**
* **Apostra refuses a refresh** because the account no longer has active access,
  or because of a platform-wide security sign-out. The refresh returns
  `invalid_grant` and your agent must send the person through sign-in again.

**Connected apps** lists the person's own sign-ins, so it is the same whichever
account they are viewing. For each one it shows the app's name, when it signed
in, and what it may do, taken from the scopes of the grant: `mcp:access` reads
as "Acts as you, with your permissions", and the HTTP API scopes
`interchange:read`, `interchange:write` and `interchange:admin` read as "Read
only" (when `interchange:read` is the only one), "Read", "Make changes" and
"Administrative operations". Each row is one sign-in, which is one grant, and **Disconnect** ends that
grant straight away. An app with several rows needs each one disconnected.

A person signing out of Apostra in their browser does **not** end the grant. The
grant belongs to your agent, not to their browser session, so your agent keeps
working until one of the events above.

## Sign in to the HTTP API

An agent can sign a person in to the HTTP API (`https://api.apostra.com/api/v3`)
with the same flow, without an API key. The HTTP API is its own protected
resource, with its own scopes, and its tokens work on `/api/v3` only. Differences
from MCP sign-in:

* Send `resource=https://api.apostra.com/api/v3` on `/authorize`, `/auth/token`
  and every refresh. Its metadata is at
  `/.well-known/oauth-protected-resource/api/v3`.
* Send `scope`, with one or more of `interchange:read`, `interchange:write` and
  `interchange:admin`. It is required. `mcp:access` and any other scope are
  refused with `invalid_scope`.
* Optionally send `account_id` to preselect an account on the approval screen.
  The person chooses the account, and the token is bound to it.
* The token response also carries `account_id`, the account the token is bound
  to, and `scope` lists the scopes it carries.

```text theme={null}
GET https://api.apostra.com/authorize
  ?response_type=code
  &client_id=https://api.apostra.com/oauth/clients/apostra-cli.json
  &redirect_uri=http://127.0.0.1:53999/callback
  &code_challenge=<S256 challenge>
  &code_challenge_method=S256
  &resource=https://api.apostra.com/api/v3
  &scope=interchange:read%20interchange:write
  &state=<opaque value>
```

[Authentication](https://docs.apostra.com/v3/authentication.md#oauth-on-the-http-api) covers what the scopes
allow, how the account binding works, and when the token stops working. An HTTP
API token is refused on every MCP endpoint, and an MCP token is refused on
`/api/v3`.

## Agents that run in a browser

A browser-based agent can run on any origin. These paths answer a request from
any origin with CORS headers and no approval step:

`/authorize`, `/auth/register`, `/auth/token`, `/auth/revoke`,
`/.well-known/*`, `/mcp`, `/mcp/*` (including `/mcp/v3`), and the per-Seller
`/seller/{id}/mcp` endpoints.

The consent step, where a person approves or denies your agent, is not on
that list. It runs only on Apostra's own pages, with that person's sign-in.

Some rules follow from that:

* **Bearer token only.** Apostra returns `Access-Control-Allow-Origin` but not
  `Access-Control-Allow-Credentials`. Send `Authorization: Bearer <access token>`
  and do not set `credentials: "include"`. Do not rely on Apostra cookies.
  A page with no token gets nothing, which is why no origin needs approval.
* **Everything else stays closed.** These paths do not open the rest of the REST
  API, such as `/api/v3/*`, to your origin. An MCP access token is rejected on
  the HTTP API anyway.
* **`null` origins are refused.** A sandboxed `srcdoc` frame or a page opened from
  a `file:` URL sends `Origin: null`, and Apostra does not answer it with CORS
  headers. Serve the agent from a real `https` origin.
* **Do not put an API key in browser code.** Use the OAuth flow above.
* **Redirect URIs still matter.** An agent on another origin can call these
  paths, but it only receives an authorization code at a redirect URI its client
  declared, and only after the person approves it.

## Agents with no person present

A background agent, a scheduled job, or a deployed backend has nobody to approve
a consent screen. Do not use this flow. Choose one of these:

* **An agent that has no credential yet** registers itself. See
  [Agent Registration](https://docs.apostra.com/v3/agent-sign-in.md#agent-registration).
* **A user API key** for simple automation. A person creates it in
  **Settings → API Access**. See [Authentication](https://docs.apostra.com/v3/authentication.md).
* **An M2M application** when your backend needs the OAuth `client_credentials`
  flow. See [Authentication](https://docs.apostra.com/v3/authentication.md).
* **An identity-only buyer-agent credential:** see
  [buyer-agent credentials](https://docs.apostra.com/v3/buyer-agents.md).

## Agent Registration

An agent with no Apostra credential, and no person to sign it in, can register
itself. It gets a sandbox to try Apostra in. The sandbox cannot spend money,
and it expires after 30 days unless your agent keeps it.

1. Read the contract at
   `https://api.apostra.com/.well-known/buyer-activation.json`. It needs no
   token. It lists the registration and token endpoints, the claim
   instructions (`claimInstructions`) and the V3 MCP endpoint
   (`mcpEndpoint`), and links the step-by-step guide at
   [`https://api.apostra.com/auth.md`](https://api.apostra.com/auth.md).
2. Register and exchange your signed assertion for an access token, as the
   guide describes.
3. Connect to the contract's `mcpEndpoint` with that token and call
   `get_status`. Your first call creates your sandbox. Its `registration`
   field shows where the sandbox stands: `status` is `sandbox` until an
   organization claims your agent, and `expiresAt` says when an unused sandbox
   is deleted ([the `registration` fields](https://docs.apostra.com/v3/tool-reference#self-registered-agents)).
   Its setup shows what your agent can do next.
4. Find sellers, your connections and your advertisers with `search` and
   `get` (`kind` `"seller"`, `"connection"` or `"advertiser"`).
5. Connect a platform and map one of its accounts to an advertiser with
   `save_connection` and `advertiserMapping`. The first mapping keeps your
   sandbox: it is no longer deleted after 30 days.

Call the endpoint URLs exactly as the contract returns them. They can name a
different Apostra host from the one you started on. Both hosts serve the same
API. The contract's `registration` and `providerBinding` entries name the V3
tool and field for steps 3 and 5. Contract 2.0 no longer lists the v2
activation endpoints that 1.3 and 1.4 did, and those endpoints are removed:
start on `/mcp/v3`.

### What the sandbox can do

Until an organization claims your agent, `get_status` shows its limits the
way it shows a person's: as setup. The checklist has one blocker,
`agent_claim` ("Claim this agent"), and its next action links the claim
instructions. Until then your agent can call `get_status`, `search` and `get`
on sellers, connections and advertisers, and `save_connection` to connect a
platform and map a platform account to an advertiser. The seller rows show
those connection steps, and none of them can be bought from yet. Any other
tool is refused with `AGENT_SIGNUP_TOOL_PROHIBITED`. These calls need no
contract or Terms of Service acceptance: the sandbox has no organization to
accept them. Once your agent is claimed, `get_status` shows the claimed
account's own setup, and the claiming organization accepts the Terms before
it can buy.

### Claiming your agent

To buy, your agent needs a person to claim it into one of their Buyer
accounts. Follow the contract's `claimInstructions`: your agent starts a claim
with the person's email address and gives them the link it gets back. The link
opens Apostra's claim page.

* **The person has an Apostra account.** They sign in, and the page lists the
  Buyer accounts they can claim your agent into: one per organization they
  belong to. They choose one, and the page shows a code. They read the code
  back to your agent, which finishes the claim with it.
* **The person has no Apostra account.** They create one from the claim page,
  even while Buyer sign-up is otherwise by request, and come back to the claim
  page to finish. They can sign up with Google, Microsoft or their company's
  single sign-on, or with their email address and a password, confirmed by a
  code Apostra emails them. This sets up a new organization with a Buyer
  account. Each agent can bring in one new person this way, and only for the
  email address the agent named. Anyone else signs in to an account they
  already have.
* **The person has no Buyer account they can use.** The page says so. An
  administrator of their organization adds a Buyer account first.

The page refuses a claim, and says why, when the link has expired or was
already used (your agent starts a new claim), when your agent started the
claim for a different email address (the person signs in with that address,
or your agent starts a new claim with theirs), and when the person has not
verified their email address yet.

The claimed account starts fresh. The platforms your agent connected and the
advertisers it mapped stay in the sandbox, so connect them again in the
claimed account.

### What a claimed agent can do

A claimed agent acts for the person who claimed it, in the Buyer account it was
claimed into. It can do what that person can do there, up to an Operator's
access:

* **Claimed by an Admin or an Operator**, the agent reads and writes. For
  example, it creates advertisers, campaigns and media buys with
  `save_advertiser`, `save_campaign` and `save_media_buy`.
* **Claimed by a Member**, the agent only reads. A write is refused with
  `ACCESS_DENIED`.
* **Admin actions stay with people**, whoever claimed the agent. Managing the
  account's members, accepting the Terms of Service, choosing a plan and
  setting payment terms or billing details are refused with `ACCESS_DENIED`.
  A person who administers the organization makes them.

The agent works only in the account it was claimed into. Naming another
account with `accountId` is refused, even one the person can reach. The
agent's access follows the person's: if their role changes, the agent's next
call uses the new role, and if they leave the account, the agent's calls are
refused.

Whether the agent can spend depends on the account's setup, not on the agent.
`get_status` lists what the account still needs; see
[Buyer setup](https://docs.apostra.com/v3/buyer-setup.md).

### When a claimed agent is revoked

An admin of the account your agent was claimed into can revoke it (see
[Agents claimed into an account](https://docs.apostra.com/v3/buyer-agents.md#agents-claimed-into-an-account)).
Apostra can revoke it too, and then emails that account's admins to say why. Revoking takes
effect on your agent's next call: every token it has, or gets later, is refused
with a `403` and `"error": "AGENT_REGISTRATION_REVOKED"`. The answer's
`message` says who revoked it, and `revokedAt` says when.

Revocation is permanent. Apostra also revokes the registration with its
identity provider. Any token your agent still gets for it is refused, and
retrying gets the same answer, so stop calling with it. To use Apostra again, register a new
agent and have a person claim it.

### Registration limits

Apostra limits how many new agents can register: a number per day, and a
number from one network source in a short window. The numbers change over
time, so this page does not list them. Only your agent's first call, the one
that creates its sandbox, counts. Later calls never count and are never
refused by a limit.

When a limit is reached, the first call gets a `429` and no sandbox is
created:

| `error` | What it means | When to retry |
| - | - | - |
| `AGENT_REGISTRATION_DAILY_LIMIT_REACHED` | Apostra has admitted today's number of new agents | After midnight UTC, when the limit resets |
| `AGENT_REGISTRATION_SOURCE_LIMIT_REACHED` | Too many new agents registered from your network recently | When the window ends |

Both answers carry a `Retry-After` header and a `retryAfterSeconds` field
with the number of seconds to wait. Send the same request again after that
time, not before.

### When registration is closed

Apostra can close Agent Registration to new agents. While it is closed,
Apostra answers:

| Request | Answer |
| - | - |
| `GET /.well-known/buyer-activation.json` | `503`, with `error.code` set to `AGENT_REGISTRATION_UNAVAILABLE` |
| `GET /auth.md` | `503`, as plain text |
| The first call of a new agent that no organization has claimed, on MCP or the HTTP API | `503`, with `"error": "AGENT_REGISTRATION_UNAVAILABLE"` |

No sandbox is created. Try again later. Retrying straight away gets the same
answer, so do not retry in a loop. To use Apostra in the meantime, have a person
sign your agent in with [OAuth](https://docs.apostra.com/v3/agent-sign-in.md#the-short-path) or give it a
[user API key](https://docs.apostra.com/v3/authentication.md).

Closing stops new registrations only. An agent that already registered keeps
working: its sandbox until the sandbox expires, and an agent an organization
has claimed for as long as the claim lasts. An agent an organization claimed
before its first call to Apostra works too, because it creates no sandbox.

## Troubleshooting

These are the messages your agent can receive. Errors from `/authorize`,
`/auth/token`, `/auth/revoke` and `/auth/register` are OAuth JSON bodies with
`error` and `error_description`.

| Error | Where | What it means | What to do |
| - | - | - | - |
| `invalid_redirect_uri` | `/auth/register` | A redirect URI breaks the [rules](https://docs.apostra.com/v3/agent-sign-in.md#redirect-uri-rules), or `redirect_uris` is missing, is not an array, is empty, or has more than 25 entries | Fix the URI. The `error_description` says which: `Invalid redirect URI`, `At least one redirect_uri is required`, `redirect_uris must be an array`, or `At most 25 redirect URIs are allowed` |
| `invalid_client_metadata` | `/auth/register` | `client_name` is not a string or is over 120 characters, or `client_uri` or `logo_uri` is not a valid `https` URL | Fix the field named in `error_description` |
| `invalid_request`, `redirect_uri is not allowed` | `/authorize` | The `client_id` and `redirect_uri` do not pair up. For a registered client: the URI is not an exact registered URI, or the registration expired. For a metadata document URL: Apostra could not fetch or validate the document, or it does not list this exact URI | Check the URI character for character. For a document, confirm the [requirements](https://docs.apostra.com/v3/agent-sign-in.md#client-id-metadata-documents) and wait about a minute, because a failed lookup is remembered that long. For a registration, register again |
| `invalid_request`, `PKCE is required...` | `/authorize` | `code_challenge` or `code_challenge_method` is missing | Send both |
| `invalid_request`, `Only S256 code_challenge_method is supported` | `/authorize` | You sent `plain` or another method | Use `S256` |
| `invalid_request`, `code_challenge must be a valid base64url-encoded string (43-128 chars)` | `/authorize` | The challenge is not base64url or is the wrong length | Use the base64url, unpadded SHA-256 of your verifier |
| `unsupported_response_type` | `/authorize` | `response_type` is not `code` | Send `response_type=code` |
| `invalid_scope` | `/authorize` | The authorization is for the HTTP API and `scope` is missing, or names a scope other than `interchange:read`, `interchange:write` or `interchange:admin` (including `mcp:access`) | Send one or more of the three `interchange:` scopes |
| `invalid_request`, `account_id must be one positive integer` | `/authorize` | `account_id` is not a single positive integer | Send one account ID, or leave it out |
| `invalid_target` | `/authorize`, `/auth/token` | The `resource` is not an exact, supported MCP endpoint or HTTP API URL on the host you called, or it differs from the one the grant was issued for. Descriptions include `resource does not identify a supported MCP endpoint`, `resource must exactly match the authorization request`, `resource must exactly match the original authorization grant`, and `authorization server hostname is not verified` (you called a host Apostra does not serve as an OAuth server) | Send the same resource every time, with no query or fragment: `https://api.apostra.com/mcp/v3` for an MCP client, or `https://api.apostra.com/api/v3` for a client calling the HTTP API |
| `invalid_grant`, `Invalid code_verifier` | `/auth/token` | The verifier does not hash to the challenge you sent to `/authorize` | Send the verifier that made that challenge, for this authorization |
| `invalid_grant`, `The authorization code binding does not match` | `/auth/token` | `client_id` or `redirect_uri` differs from the one used at `/authorize` | Send the same values |
| `invalid_grant`, `The authorization code is invalid, expired, or already used` | `/auth/token` | Codes work once and last 10 minutes | Start sign-in again |
| `invalid_grant`, `The refresh token is invalid, expired, or already used` | `/auth/token` | The refresh token was spent, revoked, or past 30 days | Start sign-in again. Next time, save each new refresh token |
| `invalid_grant`, `...Reauthorization is required.` | `/auth/token` | The account lost access, or a platform-wide sign-out ended the grant | Start sign-in again |
| `invalid_request`, `client_id is required...` or `redirect_uri is required...` or `code_verifier is required for PKCE` | `/auth/token` | A required parameter is missing from the exchange or refresh | Send `client_id` with every exchange and refresh, plus `redirect_uri` and `code_verifier` on the exchange |
| `temporarily_unavailable` (`503`) | `/auth/token`, `/auth/revoke` | Apostra's sign-in services are briefly unavailable | Retry with a short backoff |
| `AGENT_REGISTRATION_UNAVAILABLE` (`503`) | `/.well-known/buyer-activation.json`, or the first call of a new, unclaimed agent | Agent Registration is closed to new agents | Try again later. See [When registration is closed](https://docs.apostra.com/v3/agent-sign-in.md#when-registration-is-closed) |
| `AGENT_REGISTRATION_DAILY_LIMIT_REACHED` (`429`) | The first call of a new, unclaimed agent | Apostra has admitted today's number of new agents. No sandbox was created | Retry the same request after `retryAfterSeconds` (the `Retry-After` header), when the limit resets at midnight UTC. See [Registration limits](https://docs.apostra.com/v3/agent-sign-in.md#registration-limits) |
| `AGENT_REGISTRATION_SOURCE_LIMIT_REACHED` (`429`) | The first call of a new, unclaimed agent | Too many new agents registered from your network recently. No sandbox was created | Retry the same request after `retryAfterSeconds` (the `Retry-After` header). See [Registration limits](https://docs.apostra.com/v3/agent-sign-in.md#registration-limits) |
| `AGENT_REGISTRATION_STOPPED` (`403`) | Any call with an Agent Registration token | Apostra stopped this agent registration. Every token it issues is refused, and its sandbox is retired | Stop calling with it: every retry gets the same answer. To use Apostra, have a person sign your agent in with [OAuth](https://docs.apostra.com/v3/agent-sign-in.md#the-short-path) or give it a [user API key](https://docs.apostra.com/v3/authentication.md) |
| `AGENT_REGISTRATION_REVOKED` (`403`) | Any call with the token of an agent an organization claimed | An admin of the account it was claimed into, or Apostra, revoked it. Revocation is permanent | Stop calling with it: every retry gets the same answer. Register a new agent and have a person claim it. See [When a claimed agent is revoked](https://docs.apostra.com/v3/agent-sign-in.md#when-a-claimed-agent-is-revoked) |
| `error=access_denied` on your redirect URI | Redirect | The person chose **Deny** | Do not retry on a loop. Tell the person the agent is not connected |
| `Invalid or expired MCP session` | Consent screen | The person took more than 10 minutes, or the redirect URI stopped being valid | Start sign-in again |
| `401` with `WWW-Authenticate` | `/mcp/v3` | No token, an expired token, or a token issued for another endpoint | Refresh, or run the flow again for `/mcp/v3` |
| `421 Unrecognized OAuth hostname` | `/.well-known/*` | You called a host Apostra does not serve as an OAuth server | Use `https://api.apostra.com` |
| Browser says the request is blocked by CORS | Browser | The path is not one of the [browser paths](https://docs.apostra.com/v3/agent-sign-in.md#agents-that-run-in-a-browser), the request used `credentials: "include"`, or the origin is `null` | Call only those paths, send the bearer token in a header, and serve from `https` |

If sign-in still fails after you check this table, include the exact
`error` and `error_description`, the `client_id`, and the time of the failure
when you [contact support](https://docs.apostra.com/v3/support.md).

## Related

* [Authentication](https://docs.apostra.com/v3/authentication.md) covers credentials, resource binding, and
  how a person approves an MCP client.
* [MCP client setup](https://docs.apostra.com/v3/client-setup.md) has commands for Codex, Claude, and other
  hosts.
* [Render Apostra widgets in your own host](https://docs.apostra.com/v3/mcp-apps-host.md) is what a host you
  build follows, after sign-in, to show Creative Library and other widgets.
* [Connect to Microsoft Copilot Studio](https://docs.apostra.com/v2/reference/connect-copilot-studio.md) shows a
  manual client registration for a host whose wizard cannot register itself.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.