The short path
Point an MCP SDK client athttps://api.apostra.com/mcp/v3. A client that
supports MCP authorization does the rest:
- It calls the endpoint without a token and gets
401. TheWWW-Authenticateheader carries aresource_metadataURL. - It reads that metadata to find Apostra’s authorization server, then reads
/.well-known/oauth-authorization-serverfor the endpoints, includingregistration_endpointandclient_id_metadata_document_supported: true. - It identifies itself, with a Client ID Metadata Document or by registering.
- It opens a browser. The person signs in to Apostra, then approves or denies your agent on the consent screen.
- 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.
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. Yourclient_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.
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_idin the file equals the URL exactly.redirect_urisis required and each one follows the redirect URI rules. Theredirect_uriyou send to/authorizemust 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_methodout or set it tonone. Aclient_secretmakes 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-agesays, between 1 minute and 24 hours, and 5 minutes when you set none.no-storeandno-cachecount as the 1-minute minimum. It remembers a failed lookup for about a minute. A change toredirect_uristakes effect when the cached copy expires.
Dynamic client registration
Dynamic client registration is aPOST to /auth/register. Use it when you
cannot host a public file, for example a desktop tool or a local development
agent.
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_nameis 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_uriandlogo_uri, if you send them, must behttpsURLs. - 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 allowedfor 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, athttps://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 notlocalhostor[::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:
httpson any host. - Local tools:
http://localhost,http://127.0.0.1orhttp://[::1], with or without a port. No otherhttpaddress is accepted. - Desktop and mobile apps: a private-use scheme, such as
cursor://anysphere.cursor-mcp/oauth/callbackorcom.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,wssandftp. - Never: a fragment (
#...) or embedded credentials (user:pass@). A URI is at most 2048 characters.
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 theS256 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.
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.
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:
What ends a grant
A grant lasts until one of these happens:- Your agent calls the revocation endpoint.
POST /auth/revokewithtokenset to the access or refresh token (form-encoded or JSON) ends the whole grant. Sendclient_idtoo. Aclient_idthat does not match the token’s client is silently ignored, and the grant stays live. The endpoint returns200for tokens it does not recognize, and400only whentokenis 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_grantand your agent must send the person through sign-in again.
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/v3on/authorize,/auth/tokenand every refresh. Its metadata is at/.well-known/oauth-protected-resource/api/v3. - Send
scope, with one or more ofinterchange:read,interchange:writeandinterchange:admin. It is required.mcp:accessand any other scope are refused withinvalid_scope. - Optionally send
account_idto 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, andscopelists the scopes it carries.
/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-Originbut notAccess-Control-Allow-Credentials. SendAuthorization: Bearer <access token>and do not setcredentials: "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. nullorigins are refused. A sandboxedsrcdocframe or a page opened from afile:URL sendsOrigin: null, and Apostra does not answer it with CORS headers. Serve the agent from a realhttpsorigin.- 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_credentialsflow. 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.- 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 athttps://api.apostra.com/auth.md. - Register and exchange your signed assertion for an access token, as the guide describes.
- Connect to the contract’s
mcpEndpointwith that token and callget_status. Your first call creates your sandbox. Itsregistrationfield shows where the sandbox stands:statusissandboxuntil an organization claims your agent, andexpiresAtsays when an unused sandbox is deleted (theregistrationfields). Its setup shows what your agent can do next. - Find sellers, your connections and your advertisers with
searchandget(kind"seller","connection"or"advertiser"). - Connect a platform and map one of its accounts to an advertiser with
save_connectionandadvertiserMapping. The first mapping keeps your sandbox: it is no longer deleted after 30 days.
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’sclaimInstructions: 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.
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_campaignandsave_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.
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 a403 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 a429 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.
Related
- Authentication covers credentials, resource binding, and how a person approves an MCP client.
- MCP client setup has commands for Codex, Claude, and other hosts.
- Render Apostra widgets in your own host is what a host you build follows, after sign-in, to show Creative Library and other widgets.
- Connect to Microsoft Copilot Studio shows a manual client registration for a host whose wizard cannot register itself.