​

Authentication

​

Browser session host boundaries

​

Buyer signup and organization invitations

​

Password requirements

​

Recovering an interrupted signup

{
  "requiresSignup": true,
  "redirectUrl": "/signup?verified_pending=true&token=..."
}

​

Signup does not reveal existing accounts

​

Developer signup

​

Other signup experiences

​

Seller Account signup and IU plans

​

OAuth (Recommended for AI Agents)

• No API keys to create or manage
• Tokens are scoped to the authenticated user
• Works with Claude.ai (Team/Enterprise), Claude Desktop, and ChatGPT

​

MCP protocol compatibility

​

MCP OAuth resource binding

​

Managing connected apps

1. Open the account menu in the top-right corner of Apostra UI.
2. Select Connected apps.
3. Find the app you want to remove and click Disconnect.
4. Confirm the disconnection in the dialog.

​

API Keys

​

Getting Your API Key

1. Visit app.apostra.com/user-api-keys
2. Sign up or log into your Apostra account
3. Create a key while signed in as the user the integration should act as
4. Copy the key when Apostra displays it

​

User API Keys

​

Authorization

​

Existing account-owned keys

​

Embedded key management widget

# List existing account-owned keys
curl -X GET "https://api.apostra.com/api/v2/org-api-keys" \
  -H "Authorization: Bearer your_user_access_token_here"

# Revoke an existing account-owned key
curl -X DELETE "https://api.apostra.com/api/v2/org-api-keys/key_abc123" \
  -H "Authorization: Bearer your_user_access_token_here"

curl -X GET "https://api.apostra.com/api/v2/user-api-keys/widget-token" \
  -H "Authorization: Bearer your_user_access_token_here"

​

Hide fee breakdowns from a key

# Mark a key to hide fee breakdowns
curl -X PUT "https://api.apostra.com/api/v2/user-api-keys/api_key_01ABC/fee-visibility" \
  -H "Authorization: Bearer your_user_access_token_here" \
  -H "Content-Type: application/json" \
  -d '{"hidesFeeBreakdown":true}'

# List the keys your organization has marked
curl -X GET "https://api.apostra.com/api/v2/user-api-keys/fee-visibility" \
  -H "Authorization: Bearer your_user_access_token_here"

• The mark belongs to your organization. It applies only while the key authenticates into your organization.
• Apostra does not check that the ID names a key of yours. A mistyped ID marks nothing, so read the list back to confirm.
• A change can take effect on the key’s next request.
• If Apostra cannot read the mark while serving a request, the key sees total cost for that request rather than the breakdown.
• Marking applies to user API keys only. Organization-owned keys and M2M credentials are not covered.

​

Using Your API Key

curl -X GET "https://api.apostra.com/api/v2/buyer/advertisers" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json"

const response = await fetch(
  'https://api.apostra.com/api/v2/buyer/advertisers',
  {
    headers: {
      'Authorization': `Bearer ${process.env.SCOPE3_API_KEY}`,
      'Content-Type': 'application/json',
    },
  }
);

const { data } = await response.json();

import requests
import os

response = requests.get(
    "https://api.apostra.com/api/v2/buyer/advertisers",
    headers={
        "Authorization": f"Bearer {os.environ['SCOPE3_API_KEY']}",
        "Content-Type": "application/json",
    },
)

data = response.json()["data"]

​

Agent Registration

{
  "data": {
    "schemaVersion": "1.3",
    "activationId": "0198...",
    "workloadId": "agent-registration:41",
    "state": "unbound_free",
    "expiresAt": "2026-09-17T00:00:00.000Z",
    "account": null,
    "allowance": {
      "ttlDays": 30,
      "cleanup": "automatic_at_expiry",
      "spendCap": { "amountMinor": 0, "currency": "USD" },
      "grants": [
        "buyer.activation:read",
        "buyer.activation.provider-binding:write",
        "buyer.advertisers:list",
        "buyer.advertisers:read"
      ],
      "prohibitedOperations": [
        "cross_customer_access",
        "other_mutations",
        "spend_commitment"
      ]
    },
    "claim": { "available": true, "preservesActivationId": true }
  }
}

​

M2M Applications

​

Legacy scope3_ Keys

​

MCP Authentication

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { HttpClientTransport } from '@anthropic-ai/mcp-client-http';

const transport = new HttpClientTransport({
  url: 'https://api.apostra.com/mcp/buyer',
  headers: {
    'Authorization': `Bearer ${process.env.SCOPE3_API_KEY}`,
  },
});

const client = new Client({ name: 'my-agent', version: '1.0.0' });
await client.connect(transport);

const result = await client.callTool('health', {});

from mcp.client.streamable_http_transport import StreamableHttpTransport
from mcp.client import Client

transport = StreamableHttpTransport(
    "https://api.apostra.com/mcp/buyer",
    auth="your_api_key_here",
)

async with Client(transport) as client:
    result = await client.call_tool("health")

​

Verifying our signed requests

1. Ask for signatures. Add a request_signing block to your get_adcp_capabilities response. Apostra signs every operation listed in required_for or supported_for, for example:
   "request_signing": {
     "supported": true,
     "required_for": ["sync_accounts", "get_products", "create_media_buy"]
   }
   
   Without the block, calls are not signed, and your agent needs another way to recognise Apostra, such as an API key you issue for the source’s Auth field.
2. Find our key. Our agent URL is https://api.apostra.com. Its /.well-known/brand.json lists that URL in agents[], and the entry’s jwks_uri is https://api.apostra.com/.well-known/jwks.json, which publishes our Ed25519 request-signing key. You can configure that mapping directly, or discover it from the agent URL the way AdCP describes: the agent URL answers get_adcp_capabilities over MCP, over A2A (its agent card is at https://api.apostra.com/.well-known/agent-card.json), and to a plain GET with Accept: application/json, all without credentials. Its identity block gives brand_json_url and key_origins.
3. Verify. The key ID in each signature’s keyid parameter selects the key from that JWKS. The keyid is a bare key ID, such as scope3-req-sign-production. It never contains a URL: AdCP doesn’t let a signer say where its own keys are.

​

How you know a request is from Apostra

​

Two separate checks

• Who sent it? The signature. Our agent’s own record, https://api.apostra.com/.well-known/brand.json, lists our agent and its keys. apostra.com/.well-known/brand.json describes the Apostra brand and lists no agents, so don’t look for our keys there.
• May this agency act for this brand? The brand’s own brand.json answers this through its authorized_operators, which names the agencies allowed to buy for it.

​

Check your setup

​

Base URLs

​

Versioning

​

Account availability

• register its organization as an Apostra Partner or grant commercial Partner approval;
• grant certification, contract readiness, or Apostra listing readiness; or
• choose whether a Buyer operates in sandbox or production.

​

Terms of Service acceptance

• An account member who is not a direct admin of its parent organization cannot accept the parent’s ToS. They must join the parent organization as an admin first.
• A direct member at a non-admin level (BASIC, PREMIUM) also cannot accept — only ADMIN / SUPER_ADMIN levels qualify.

​

If your organization has no admin

• How you find out. When canAcceptTos is false, the current-user responses (GET /auth/me, POST /api/v2/accounts/switch, and the user_get_current tool) also carry organizationHasAdministrator. It is false when the organization governing your account has no admin, and it is omitted when you can accept.
• Whether you can ask. When organizationHasAdministrator is false, the same responses carry canRequestOrganizationAdmin, which says whether you can file the request from the account you are in right now. When it is false, organizationAdminRequestBlockedReason says why: staff_session (Apostra staff are impersonating a user or viewing the account through platform support without a membership, so no request is filed in a customer’s name), not_a_member (you have no membership in the account), organization_has_admin, organization_setup_incomplete (the account has no organization; contact support), or unavailable (the check could not be made; try again). The same responses carry organizationAdminRequestCustomerId, the account the decision was made for: the organization when you belong to it, otherwise the account you act in. The web app shows the button only when it is true and otherwise shows the reason.
• How you ask. In the web app, the blocking ToS notice shows Request organization admin in place of Notify your admins. Through the API, call POST /api/v2/accounts/request-organization-admin. The optional body field customerId names the account to file from; send organizationAdminRequestCustomerId so the request is judged for the same account the button was offered for, whatever account your request headers select. You must be a direct member of that account. Without a body it acts on the organization of the account you are operating in. It returns organizationId, requestId, status (pending or approved), and created.
• One request per person. You get one request for each organization. Asking again returns the same request with created: false and does not notify Apostra again.
• Who can ask. You must be a member of the account you file from (the account in customerId, else the account you are operating in). The request is refused with 409 if the organization already has an admin, and with 403 if you are not a member of the account or an API key lacks interchange:admin. Staff impersonating or simulating a user cannot make the request. Staff in a platform support session who are not members of the account get staff_session as the reason; staff who are direct members of the account can request as any member can.
• If you would have owned the organization at signup, you are approved at once. Signing up with a verified email on an organization’s domain makes you its admin when it has no admin. A request follows the same rule. When the organization has no admin and no pending admin invitation, and you are signed in with a verified email on the organization’s domain, the call approves your request itself and returns status: "approved" with created: true. It is the approval Apostra staff would give: an admin invitation is emailed to you, and in the web app the notice shows an Accept link right away. You become an admin by accepting that invitation, then accept the ToS. Apostra staff are not asked. Nothing makes you an admin before you accept.
• Everyone else waits for review. Any other request returns status: "pending" and goes to Apostra staff. That includes an email on a different domain, a domain not registered to the organization or shared by several accounts, a personal email address, a mailbox that is not verified, and an organization that already has a pending admin invitation. If an admin appears while the call is running, it returns 409; if an admin invitation appears, the request stays pending.
• What happens next. For a pending request, Apostra staff review it. If it is approved, you receive an invitation by email to become an admin of the organization. Accept it from the pending invitation (see below), then accept the ToS. Nobody becomes an admin without an approval, and an approval is either Apostra staff’s or the signup rule above.
• If you would rather email. Write to support@apostra.com.

​

When updated terms are published

• A patch that does not materially change the terms, or is wholly favorable to customers, is a notice-only update. Existing acceptance continues without an interruption.
• A material minor or major update requires an organization administrator to accept. Before the displayed deadline, eligible administrators see the review prompt and can choose Review later; other members can continue working during that review period.
• Once the deadline passes, account activity pauses until an eligible administrator accepts. Non-admin members then see a notice telling them to contact an administrator, while the account selector remains available.

​

Citing an exact published revision

​

Next Steps