JWTs and JWKS
Use core keys for agent-facing AIGW tokens, per-resource keys for assertions sent to the merchant authorization server, and merchant keys for merchant-issued tokens.
Token and assertion reference
| Credential | Issued/signed by | Held by / sent to | Audience or binding | Validation keys |
|---|---|---|---|---|
| AIGW access token | Core AIGW authorization server | Agent → MCP/UCP service; service → AIGW for redemption | Expected Resource audience, required scopes, Project and login context | Core jwks_uri from Resource discovery |
| AIGW ID token | Core AIGW authorization server | Agent's OIDC client | Agent client_id; validate transaction nonce | Core jwks_uri from discovery |
| Proxy token | Core AIGW authorization server | MCP/UCP service → AIGW in X-Proxy-Token | Proxy client and Project; validated by AIGW | Core issuer; normally consumed by AIGW, not the merchant API |
| Merchant access token | Merchant authorization server | AIGW Token Vault → MCP/UCP service → merchant API | Merchant API audience and granted permissions, as defined by merchant AS | Merchant AS validation configuration |
| User assertion | AIGW Resource signing key | AIGW → merchant token endpoint | Configured merchant Issuer URL in JWT aud | Per-resource JWKS; iss is the per-resource issuer |
| Client assertion | AIGW Resource signing key | AIGW → merchant token endpoint for JWT client authentication | Configured merchant Issuer URL in JWT aud | Per-resource JWKS; iss and sub are the merchant-side Client ID |
An assertion is input to a merchant access token grant; it is not the token the agent sends to your MCP service. The Resource indicator identifies the protected Resource and is sent during credential redemption. It is distinct from the merchant issuer used as the assertion's aud, and from the optional RFC 8693 request-body audience parameter.
1. Agent-facing AIGW tokens
The per-resource discovery document reports the global/core issuer and core JWKS. AIGW access tokens issued to agents come from this core context.
Issuer: https://core.api.aigw.loginid.ai/
JWKS: https://core.api.aigw.loginid.ai/.well-known/jwks.json
For JWT verification, allow only the algorithms configured for your integration; the Node.js validation example uses RS256 for core-issued tokens.
For access-token permissions, read the scp array or the space-delimited scope string. If both appear, require matching sets. The OAuth token response's scope field is separate from these signed JWT claims. See the validation example.
2. Merchant-facing Resource assertions
AIGW signs user assertions and client assertions with the Resource's ES256 key.
Issuer: https://api.aigw.loginid.ai/<RESOURCE_ID>
JWKS: https://api.aigw.loginid.ai/<RESOURCE_ID>/.well-known/jwks.json
Alg: ES256
The merchant authorization server uses this keyset for both user and client assertions. The user assertion has the per-resource issuer; the separate client assertion has the merchant client ID as issuer, as shown below. Neither uses the core token JWKS.
User assertion claims
| Claim | Value |
|---|---|
iss | per-resource AIGW issuer |
sub | User identifier presented to the merchant: an email from the user's sign-in provider or the AIGW pairwise subject; see user matching |
aud | configured merchant issuer URL |
iat / exp | Assertion validity window; 5 minutes by default |
jti | unique ID |
Client assertion claims
| Claim | Value |
|---|---|
iss | merchant-AS client ID |
sub | merchant-AS client ID |
aud | configured merchant issuer URL |
iat / exp | Assertion validity window; 5 minutes by default |
jti | unique ID |
Rotation
Resource JWKS can contain older, non-active keys as well as the active key. Merchant verifiers should select by kid and refresh JWKS when encountering an unknown key.
Audience and user/agent claims
The Resource indicator, platform-token audience, and merchant assertion audience serve different purposes. AIGW sets user/client assertion aud to the configured merchant Issuer URL. Use the exact value, including its path and trailing-slash convention, in merchant JWT validation.
AIGW releases identity claims by granted scopes: profile for name/birthdate/address, email for verified email fields, and phone for phone_number/phone_number_verified. Available claims depend on what authentication established. Email/passkey possession does not by itself prove a person's full identity. The ID token/userinfo carries the released identity; the access token carries authorization context rather than those human identity claims.
For agent clients, access-token extensions and merchant assertions can carry act and agent (client, domain, verification/KYA evidence). The merchant authorization server decides what is retained in its own token. Scope consent and the relying party's own authorization rules still apply.