Skip to main content
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.

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 or by registering.
  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: 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.
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. 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.
  • 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.
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 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 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.
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.
The response is a standard token response with token_type: Bearer, scope mcp:access, and: Both tokens are bound to the person, your client, and the exact resource. Refresh before the access token expires:
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.
Authentication 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.
  • A user API key for simple automation. A person creates it in Settings → API Access. See Authentication.
  • An M2M application when your backend needs the OAuth client_credentials flow. See Authentication.
  • An identity-only buyer-agent credential: see buyer-agent credentials.

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

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). 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: 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: 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 or give it a user API key. 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. 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.