Authentication & credentials

Overview

Every request to the API is authenticated. Which credential you present depends on who is acting and what they are doing:

• A Client onboarding Principals and agents presents its Client API key.
• The same Client API key authorizes transactions and manages agents, mandates and webhooks. On these runtime endpoints it acts for one of your Principals (see Acting for a Principal). A short-lived OAuth2 Bearer token can stand in for the key on the runtime endpoints.
• Mandate Labs runs Client lifecycle internally with the Admin master key; integrators never hold or present it.

API keys travel in the X-API-Key header, and the key prefix selects the environment. (X-Admin-Key is the internal operator header Mandate Labs uses for Client provisioning; it is not part of the developer-facing surface.) Keys are never stored in the clear: the server stores only a SHA-256 hash and compares hashes on every request.

The credential planes

Acting for a Principal

Runtime resources (agents, mandates, authorizations, webhooks, thresholds) belong to a Principal. When you call the runtime API with your Client API key or a Client OAuth token, the platform picks the acting Principal in this order:

A sandbox Principal key always acts for its own Principal; the header is not consulted.

Sandbox vs live routing

There is no separate hostname or header for the sandbox. The key prefix alone selects the environment, and the platform routes the request to the matching database:

This means a single integration can target either environment just by swapping the key. Sandbox and live data are fully isolated: a mdt_test_ key never sees production records, and OAuth tokens carry the environment they were minted in.

Scopes

A credential can be restricted to a subset of the API with scopes: a comma-separated list set when the key is issued. An empty scope or * means full access; otherwise the request's path must map to one of the allowed scopes or it is rejected with 403.

Scopes are resolved by URL prefix. A key scoped authorize can reach any path under /api/v1/authorize but nothing else. Common scopes:

Issue least-privilege credentials: a service that only authorizes transactions should carry the authorize scope and nothing more, so a leaked key cannot manage agents or read unrelated data. The scope is enforced on every request, and for OAuth2 the scope is frozen into the access token at mint time.

IP allowlists

A credential can additionally be bound to a set of source IPs. If an allowlist is configured, requests from any other origin are rejected with 403 before the request is processed.

The check is proxy-aware: the real client IP is resolved through the trusted-proxy chain, so a caller cannot spoof its way past the allowlist by setting its own X-Forwarded-For header. Leave the allowlist empty (the default) for unrestricted origins; set it to lock a production key to your egress IPs.

Rotation, expiry & revocation

Your Client credential has a full lifecycle, all managed by Mandate Labs on your behalf.

Issue

Your Client credential is issued to you during onboarding, and issuance is additive: new keys don't invalidate existing ones. Each key can carry scopes, an IP allowlist, an environment (live or sandbox), and an expiry. The raw key is shown once.

Rotate with a grace window

Rotation is zero-downtime. Mandate Labs issues a new key while the previous key stays valid as a previous key for a grace window (24 hours by default). During that window both keys authenticate, so you can roll the new key out everywhere before the old one stops working. Once the grace period lapses, the previous key is no longer accepted.

Expiry

A credential issued with an expiry stops authenticating after that date; requests then fail with 401. Expiry is enforced on every request and, for OAuth2, also bounds how long a derived access token can outlive the underlying key.

Revoke

If a key is compromised, Mandate Labs revokes it immediately on request. Revocation is irreversible; to restore access, a new credential is issued.

Per-Principal sandbox keys

In the sandbox, a freshly onboarded dev Principal can mint its own sandbox key via POST /principals/{id}/sandbox-key (sandbox credentials only). This lets the dev drive the per-Principal endpoints (authorize, mandates, reads) without ever exposing the Client's master credential. It is a sandbox-only affordance; per-Principal keys are not part of the production credential model.

Which auth each API group needs

Header reference

The exact request shape for each plane.

Client API key · onboarding

curl -X POST https://api.mandatelabs.ai/api/v1/onboard \
  -H "X-API-Key: mdt_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: onboard-acme-001" \
  -d '{ "principal": { … }, "agent": { … }, "mandate": { … } }'

Client API key · authorize

curl -X POST https://api.mandatelabs.ai/api/v1/authorize \
  -H "X-API-Key: mdt_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agt_…",
    "amount": "42.00",
    "currency": "USD",
    "mcc": "5812",
    "intent_context": { "task_reference": "Lunch order for the team" }
  }'
# The acting Principal is the one that owns agt_…

Client API key · acting for a specific Principal

# Needed on runtime endpoints other than /authorize when your Client has more than one Principal
curl https://api.mandatelabs.ai/api/v1/webhooks \
  -H "X-API-Key: mdt_live_…" \
  -H "X-Principal-Id: prn_…"

OAuth2 · exchange credentials for a Bearer token

curl -X POST https://api.mandatelabs.ai/api/v1/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=moc_live_…" \
  -d "client_secret=mos_…"

# then call the runtime API with the token (same acting-Principal rules as the Client API key)
curl -X POST https://api.mandatelabs.ai/api/v1/authorize \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{ "agent_id": "agt_…", "amount": "42.00", "intent_context": { "task_reference": "…" } }'

{
  "access_token": "eyJ…",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "authorize,agents"
}

Next steps