Skip to main content
Connect to https://api.apostra.com/mcp/v3 with interactive OAuth or call https://api.apostra.com/api/v3 with an API key or an M2M application. The credential determines the home account, reachable accounts, and permissions; the URL does not select Buyer or Seller behavior.
  • Use MCP OAuth for interactive clients and human-authorized work. Its access tokens are bound to the MCP resource and are rejected by HTTP API routes.
  • Use a user API key for simple headless automation, stored in a secret manager and sent as Authorization: Bearer YOUR_API_KEY. A key acts as its owner and is bound to the organization selected when it was created.
  • Use an M2M application when your deployed backend requires the OAuth client_credentials flow. Request the token endpoint and resource indicator returned when you create the M2M application. Send the resulting token as a bearer credential to the HTTP API.
  • Grant only the permissions the integration needs. A visible tool may still refuse a write when the credential lacks the required permission.
Most HTTP operations require one permission for every request. save_billing has two levels: interchange:read can poll an existing handoff only when paymentAuthority.action is status; accepting Terms and requesting or confirming payment authority require interchange:write. Its OpenAPI security entry declares the minimum interchange:read permission, while x-interchange-invocation-permissions records the request-specific rule. A read-only mutation is rejected before a billing service runs.

​
Payment-authority status access

Polling payment-authority status is a read-scoped operation, but a human caller must still be an account admin. A user API key, WorkOS M2M credential, or organization API key may make the same check with interchange:read when the credential is bound to the effective organization. The status response contains the handoff method, state, and expiry. It does not return card details or the capture-link URL. Advertiser-scoped credentials cannot read it. When a child account inherits billing from a parent, a person must be a direct admin of that parent; a credential bound to the child is rejected at the parent boundary. This read access does not widen mutation access. Accepting Terms or requesting or confirming payment authority still requires interchange:write, the same credential-to-organization match, and the existing account safeguards. Call get_status after authentication to verify the selected account and its readiness. Every authenticated Buyer and Seller Account can connect; individual operations still require the appropriate permissions and resource access. For an API key or M2M credential that can reach more than one account, send X-SCOPE3-CUSTOMER-ID with an accessible customer ID. Apostra rejects a customer outside the credential’s scope. The header selects context only; it does not grant access. An agent should direct a person to Settings → API Access to create a user API key. It cannot retrieve an existing secret, and a long-lived credential must not pass through chat. Existing organization-owned keys remain supported during migration; they are not the default for a new integration.

​
OAuth resource binding

OAuth discovery for v3 advertises https://api.apostra.com/mcp/v3 as the exact protected resource. MCP clients carry that URI through authorization, token exchange, and refresh. Apostra issues dedicated MCP access and refresh credentials for that resource; a v3 interactive credential is rejected on another MCP endpoint or on the HTTP API. Do not reuse an MCP access token for /api/v3/tools/*. The protected-resource metadata document is available at https://api.apostra.com/.well-known/oauth-protected-resource/mcp/v3. Clients should follow the resource_metadata URL in the server’s WWW-Authenticate challenge instead of constructing it themselves.

Full authentication reference

Review OAuth, user API keys, M2M applications, permissions, and stable v2 versioning behavior in the canonical authentication guide.