Get a merchant access token
The MCPMCPModel Context Protocol: a standard way for AI agents to call tools and data sources exposed by a server./UCP service uses two server-side calls to obtain the merchant token associated with the user's authorization.
Why two tokens are involved
The agent gives your server the AIGW access tokenAIGW access tokenThe token an agent receives after the user authorizes it. It says which user approved which agent for which scopes. representing the authorized user/agent session. Your server separately proves its own identity to AIGW with a project-level Proxy clientProxy clientThe server-side credential (client ID and secret) the MCP/UCP service uses to authenticate itself to AIGW. Never give it to an agent. credential. AIGW requires both contexts before it returns the merchant token.
This prevents the agent from directly redeeming merchant credentials and prevents an MCP/UCP server from redeeming a user token from a different AIGW project.
Step 1 — Get a proxy token
Use OAuth client_credentials against the AIGW core token endpoint:
POST https://core.api.aigw.eval.loginid.ai/oauth2/token
Authorization: Basic base64(<PROXY_CLIENT_ID>:<PROXY_CLIENT_SECRET>)
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials
The supplied test returned 200, expires_in: 3599, and a bearer token. Cache this token until near expiry instead of obtaining a new one for every MCP call.
Step 2 — Redeem for the merchant token
Call the AIGW credential endpoint:
POST https://api.aigw.eval.loginid.ai/api/credentials/token
Authorization: Bearer <AIGW_ACCESS_TOKEN_FROM_AGENT>
X-Proxy-Token: <PROXY_TOKEN>
Content-Type: application/json
{
"resource": "https://api.example.com/search"
}
The resource value must exactly match the Resource indicatorResource indicatorThe exact identifier (audience) of the merchant API. The MCP/UCP service sends the same value when redeeming the merchant token. / audience configured on the AIGW Token exchange ResourceToken exchange ResourceA Resource for agent access: AIGW authorizes the user and obtains a token from the merchant's own authorization server.. A different URL or trailing slash is not interchangeable.
A successful response contains the merchant access tokenMerchant access tokenA token issued by the merchant's own authorization server. Only the MCP/UCP service sees it, never the agent., its expiry, and the scopes the merchant authorization server granted:
{
"access_token": "<MERCHANT_ACCESS_TOKEN>",
"expires_at": "2026-10-15T17:10:41Z",
"scopes": ["profile", "email", "address", "checkout", "shipping"]
}
The merchant refresh token is never returned; AIGW keeps it and refreshes on your behalf.
Project matching rule
The AIGW user token and proxy tokenProxy tokenA short-lived token the MCP/UCP service gets with its Proxy client, sent as X-Proxy-Token when redeeming a merchant token. must belong to the same Project. Redemption fails when the Proxy client belongs to a different Project than the user's token.
When the merchant token is actually provisioned
The current backend implementation attempts merchant-token provisioning at user login/authorization completion. It is best effort: a failure is logged and does not block sign-in. AIGW caches the external token by project, user subject, and resource.
The credential redemptionCredential redemptionPOST /api/credentials/token: the MCP/UCP service trades the user's AIGW token plus its Proxy token for the merchant access token. call then reads that cached token and refreshes it when needed. If a refresh token exists, AIGW uses it; otherwise it re-asserts to the merchant authorization server.
Merchant-token provisioning is best effort. A user can complete sign-in even if it fails, and the failure may only surface when the MCP/UCP server later tries to redeem the credential.
How AIGW talks to the merchant authorization server
For the supplied private_key_jwt configuration, AIGW sends:
- an RFC 7523 JWT bearer grant containing a user assertion; and
- JWT client authentication (
client_assertion) for AIGW's merchant-AS client.
The user assertion is ES256-signed using the ResourceResourceThe downstream system registered in a Project. Its kind (Token exchange or OAuth client) decides the role AIGW plays. signing keySigning keyA per-Resource ES256 key AIGW uses to sign assertions sent to the merchant authorization server, published at the Resource JWKS URL.. The relevant claims are:
| Claim | Value |
|---|---|
iss | AIGW per-resource issuer https://api.aigw.eval.loginid.ai/<RESOURCE_ID> |
sub | Candidate external reference: login-evidence email(s), then AIGW pairwise subject |
aud | Merchant authorization-server issuer configured as Issuer URL |
iat, exp | Current time and configured assertion lifetime |
jti | Unique UUID |
The client assertion uses the merchant-AS client ID as iss and sub and the same merchant issuer as aud.
User matching fallback
The supplied backend tries each email from login evidence in order, then the AIGW pairwise subject. It only advances to the next candidate when the merchant AS returns invalid_grant with an error description containing user not found (case-insensitive). Other errors stop the attempt.
This means the merchant IAM integration needs an explicit strategy for user lookup/provisioning. See Merchant Authorization Server.
A successful redeem was verified end to end with the Playground against a private_key_jwt Resource backed by Keycloak. AIGW returned a Keycloak-issued merchant token (azp: token_exchange_client, aud containing the Resource indicator) with the response shape above. Missing redemption headers were separately confirmed to return 400.