Identity broker API

Every endpoint of the MAQPNA identity broker - token mint, verify, DPoP bind, proof nonces, RFC 8693 exchange and A2A delegation, JWKS, OIDC discovery, warm-pool bootstrap and probes - plus the session-token claims.

The identity broker (maqpna-identity) issues each session a short-lived, signed identity: a session token. This page is the reference for its HTTP API and for the claims inside the tokens it issues.

You rarely call the broker yourself. The operator mints tokens when it starts a session, the gateway fetches the broker's public keys (JWKS), and SDKs read the token from the file the operator mounts. You need this page when you debug a token, mint one by hand for a test, exchange a token for a cloud credential, implement A2A delegation without an SDK, or write a verifier. For the concepts, read Identity and delegation; for the design, Identity broker.

Source: cmd/maqpna-identity (broker.go, delegation.go, dpop.go, checks.go, bootstrap.go) and pkg/identity.

Endpoints at a glance#

sequenceDiagram
    autonumber
    participant OP as Operator
    participant IB as Identity broker
    participant AG as Agent A
    participant GW as Gateway
    participant B as Agent B
    OP->>IB: POST /v1/token (Bearer MAQPNA_BROKER_TOKEN)
    IB-->>OP: {token, expiresAt, spiffeId, jti, kid}
    OP->>AG: token file, re-minted at 80% of the lifetime
    GW->>IB: GET /.well-known/jwks.json
    AG->>GW: POST /a2a/team-a/reviewer (scope agents:reviewer)
    GW->>B: call + Txn-Token
    B->>IB: POST /v1/exchange<br/>subject_token = Txn-Token, actor_token = B's token
    IB-->>B: delegated token (act: A, then the user)

Authentication#

A wrong broker token returns 401 {"error":"unauthorized"} with WWW-Authenticate: Bearer realm="maqpna-identity". All JSON responses carry Cache-Control: no-store, except the key documents. Request bodies are limited to 64 KiB.

POST /v1/token#

Mint a session token. Unknown body fields are rejected.

curl -sS -X POST http://localhost:8081/v1/token \
  -H "Authorization: Bearer $MAQPNA_BROKER_TOKEN" -H "Content-Type: application/json" \
  -d '{"namespace":"team-a","agent":"coder","session":"fix-4821","user":"[email protected]","scopes":["tools:github","models:team-a.coder"],"tier":"tier-1","ttlSeconds":900}'

{
  "token": "eyJhbGciOiJFZERTQSIsImtpZCI6Ik56YkxzWGg4dURDY2QtNk1Od1hGNFdfN25vV1hGWkFmSGt4WnNSR0M5WHMifQ.…",
  "expiresAt": "2026-10-18T14:20:00Z",
  "spiffeId": "spiffe://maqpna.local/ns/team-a/agent/coder/session/fix-4821",
  "jti": "b3f1c2…",
  "kid": "NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs",
  "tokenType": "Bearer"
}

tokenType is DPoP for a bound token. substrate is added when a proof was verified.

CLI: maqpna token mint.

Proofs and POST /v1/proof/nonce#

With identity checks configured (-identity-checks, -sandbox-check), a mint can carry a proof that the broker verifies against the substrate itself and records in the maqpna_substrate claim:

POST /v1/proof/nonce with body {"check": "<name>"} returns {"check", "nonce", "expiresAt"} for a check that issues nonces; 400 for one that does not. See Identity checks.

POST /v1/token/verify#

Verify a token's signature, issuer, expiry, audience and tenant key binding.

curl -sS -X POST http://localhost:8081/v1/token/verify \
  -H "Authorization: Bearer $MAQPNA_BROKER_TOKEN" -H "Content-Type: application/json" \
  -d "{\"token\":\"$(cat token.jwt)\"}"

A valid token returns 200 {"valid": true, "claims": {...}}; an invalid one returns 200 {"valid": false, "error": "<why>"}. A body without token is 400. CLI: maqpna token verify (which checks against the JWKS) and maqpna token inspect (which decodes).

POST /v1/token/bind#

Exchange an unbound session token for the same token bound to a DPoP key (RFC 9449). Present the token as Authorization: Bearer <token> and a DPoP header with a proof over it (ath). A token's jti binds to one key only: the first bind wins.

{"token":"eyJ…","tokenType":"DPoP","expiresAt":"2026-10-18T14:20:00Z","jti":"b3f1c2…","jkt":"0ZcOCORZNYy-DWpqq30jZyJGHTN0d2HglBV3uiguA4I"}

Errors carry WWW-Authenticate: DPoP algs="EdDSA ES256", error="<code>". The bind record lives in the replica's memory, so with several broker replicas a token can be bound once per replica. See DPoP.

POST /v1/exchange#

RFC 8693 token exchange. The body is application/x-www-form-urlencoded (RFC 8693) or JSON with the same parameter names. Errors follow RFC 6749: {"error", "error_description"}.

Exchange (no actor token)#

The subject token must be a MAQPNA session token (not itself an exchanged token). The audience must be on the -exchange-config allow-list, and the subject's namespace must match the audience's allowedNamespaces. The issued token holds only the requested scopes that are both allowed for the audience (allowedScopes) and granted by the subject; it lives at most maxTTLSeconds (default 300) and never longer than the subject; it carries maqpna_parent_jti. A provider on the audience turns the MAQPNA token into a cloud credential (aws-sts, gcp-sts, azure-entra); without one, the result is a down-scoped MAQPNA token.

-exchange-config file:

{
  "audiences": {
    "github-mcp": {"maxTTLSeconds": 300, "allowedScopes": ["tools:github"], "allowedNamespaces": ["team-a"]},
    "aws-prod": {"provider": "aws-sts", "params": {"roleArn": "arn:aws:iam::123456789012:role/agent"}, "allowedNamespaces": ["team-a"]}
  }
}

The params keys depend on the provider; see Cloud identity and keys.

curl -sS -X POST http://localhost:8081/v1/exchange \
  -d grant_type=urn:ietf:params:oauth:grant-type:token-exchange \
  -d "subject_token=$(cat "$MAQPNA_TOKEN_FILE")" \
  -d subject_token_type=urn:ietf:params:oauth:token-type:jwt \
  -d audience=github-mcp \
  -d scope=tools:github

{"access_token":"eyJ…","issued_token_type":"urn:ietf:params:oauth:token-type:jwt","token_type":"Bearer","expires_in":300,"scope":"tools:github"}

A DPoP-bound subject token needs a proof by its key when the audience has a provider (cloud credentials are bearer); down-scoping it to a MAQPNA token needs none and keeps the binding.

A2A delegation (with an actor token)#

Agent B, handling an A2A call from agent A, exchanges for a token that records the chain. actor_token is B's own session token (not exchanged, not delegated). subject_token is either:

• the call's transaction token from the gateway (subject_token_type = urn:ietf:params:oauth:token-type:txn_token), which must have been issued for a call to B; or
• A's session token (jwt / access_token / empty type), which must grant agents:<B> (agents:<ns>/<B> across namespaces) and must not be DPoP-bound.

audience, when set, must be the broker's default audience. The result is a token for B whose act chain is A and then the user, with maqpna_delegator_jti. It lives at most 15 minutes (or requested_ttl_seconds), the chain is capped at -max-delegation-depth (5), and a delegation never crosses a tenant. A DPoP-bound actor token needs a proof by its key.

curl -sS -X POST http://localhost:8081/v1/exchange \
  -d grant_type=urn:ietf:params:oauth:grant-type:token-exchange \
  -d "subject_token=$TXN_TOKEN" \
  -d subject_token_type=urn:ietf:params:oauth:token-type:txn_token \
  -d "actor_token=$(cat "$MAQPNA_TOKEN_FILE")"

The response has the same shape as an exchange (issued_token_type urn:ietf:params:oauth:token-type:jwt). Errors: invalid_request, invalid_target, invalid_grant (bad actor or subject, wrong call target, different tenants, bound subject token), invalid_scope (subject_token does not grant agents:<name>), invalid_dpop_proof, temporarily_unavailable. See Agent-to-agent calls.

GET /.well-known/jwks.json#

The broker's public keys: the current signing key, retired keys still trusted (-previous-keys), every tenant key, and, when configured, the ML-DSA key and the federation key. Content-Type: application/jwk-set+json, Cache-Control: public, max-age=300.

curl -sS http://localhost:8081/.well-known/jwks.json

{"keys":[{"kty":"OKP","crv":"Ed25519","x":"11qYAYKxCrfVS_7TyWQHOg7hcvPapiMlrwIaaPcHURo","kid":"NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs","use":"sig","alg":"EdDSA"}]}

MAQPNA verifiers use the OKP keys (and ML-DSA keys when identity.acceptMLDSA is set) and ignore others. The gateway refreshes this document every 300 s and at once on an unknown kid (at most every 10 s).

OIDC discovery for cloud federation#

With -federation-key (an ES256 or RS256 key) the broker signs federation JWTs that AWS STS, Google STS and Microsoft Entra accept, and serves two documents for the federation issuer (-federation-issuer, default -issuer):

GET /.well-known/openid-configuration:

{
  "issuer": "https://identity.example.eu",
  "jwks_uri": "https://identity.example.eu/.well-known/federation/jwks.json",
  "response_types_supported": ["id_token"],
  "subject_types_supported": ["public"],
  "id_token_signing_alg_values_supported": ["ES256"],
  "claims_supported": ["sub", "aud", "iss", "iat", "exp", "nbf", "jti", "maqpna_ns", "maqpna_agent", "maqpna_session", "maqpna_tier", "scope"]
}

GET /.well-known/federation/jwks.json holds only the federation key. Both are cached for 300 s. The issuer URL must route to the broker, or you host these two documents statically. See Hyperscaler interop.

POST /v1/bootstrap#

Warm-pool late binding: a pre-started pod learns which session it serves. Served only on -bootstrap-listen, the one broker port agent namespaces may reach.

The broker runs a TokenReview, checks the bound pod, follows pod → Sandbox → SandboxClaim → AgentSession with matching UIDs, binds the first pod, and returns the session:

{
  "namespace": "team-a",
  "session": "fix-4821",
  "agent": "coder",
  "attested": false,
  "token": "eyJ…",
  "expiresAt": "2026-10-18T14:20:00Z",
  "spiffeId": "spiffe://maqpna.local/ns/team-a/agent/coder/session/fix-4821",
  "jti": "b3f1c2…",
  "env": {"MAQPNA_GATEWAY_URL": "<gateway URL>", "MAQPNA_SESSION": "fix-4821", "…": "…"}
}

Attested sessions (tier-2) get no token: they redeem their release ID with attestation evidence. Call again with the rotated ServiceAccount token to refresh before expiresAt.

Probes, version and metrics#

Token claims#

Session tokens are compact JWS. The header is {"alg":"EdDSA","kid":"<RFC 7638 thumbprint>"} (ML-DSA-* when -sign-alg selects it). Verifiers reject other algorithms, refuse tokens with typ: txntoken+jwt (a transaction token is never an identity token), and accept a token without kid only when exactly one key is trusted.

Decode one locally:

maqpna token inspect "$(cat "$MAQPNA_TOKEN_FILE")"

Broker flags that shape the API#

The complete list is maqpna-identity -h; environment variables are in Environment variables.

Next steps#

• Gateway data-plane API: where session tokens are used
• Admin API: revocations and the rest of /v1/*
• Key management: rotate the signing key without breaking tokens
• Identity broker flow: the sequences behind mint, bootstrap and delegation
• Connect to the gateway: how SDKs read and refresh the token