Credential redemption

Credential redemption

Trade the user's AIGW token and your Proxy token for the merchant access token.

Checked against the Evaluation environment, Console 0.10.1 / 0.14.1, on October 19, 2026. Release status

Redemption is how an MCP or UCP service reaches the merchant API on the user's behalf. The agent never sees the merchant token: it holds only the AIGW token, and your service exchanges that for the merchant token on the server.

Endpoint

http
POST https://api.aigw.eval.loginid.ai/api/credentials/tokenContent-Type: application/json

Before you call it

  • The agent called you with Authorization: Bearer <AIGW token> and you validated it. The token must carry ext_token:read, a resolved Project and a login ID.
  • You hold a Proxy token from the client credentials grant, for a Proxy client in the same Project as the Resource that issued the user's token.
  • You know the exact Resource indicator of the merchant API, as configured on the Token exchange Resource.
  • The merchant's authorization server trusts AIGW. See Configure your authorization server.

Request

Headers

Authorization
headerRequired
Bearer followed by the user's AIGW access token, exactly as the agent sent it. An ID token is not a substitute.
X-Proxy-Token
headerRequired
Your service's Proxy access token, sent bare without a Bearer prefix.
Content-Type
headerRequired
application/json

Body

resource
string (URL)Required
The merchant API's Resource indicator, resolved against Resources in the Project. Must match the Token exchange Resource configuration character for character, including scheme, path and trailing slash. Example: https://api.example.com/search.
curl -s -X POST "https://api.aigw.eval.loginid.ai/api/credentials/token" \  -H "Authorization: Bearer $AIGW_ACCESS_TOKEN" \  -H "X-Proxy-Token: $PROXY_TOKEN" \  -H "Content-Type: application/json" \  -d '{ "resource": "https://api.example.com/search" }'

Response

Response200 OKjson
{  "access_token": "<MERCHANT_ACCESS_TOKEN>",  "expires_at": "2026-10-15T17:10:41Z",  "scopes": ["search:read"]}
access_token
stringRequired
The token the merchant's authorization server issued for this user. Send it to the merchant API as Authorization: Bearer.
expires_at
string (RFC 3339)
When the merchant token expires. Can be absent.
scopes
string[]
Scopes the merchant token carries. Can be absent.

The merchant refresh token is never returned.

Keep the merchant token on your server

Never return the merchant token to the agent, put it in a tool result, or log it. If an agent could read it, the agent could call the merchant API directly, outside AIGW's policy.

Caching and refresh

AIGW tries to provision the merchant token when the user completes login, and caches it by Project, user subject, Resource and login ID. Provisioning is best effort: sign-in can succeed even when it failed. Redemption reads from that cache and refreshes lazily near expiry, so you can call this endpoint on every agent request. If you add your own cache, key it the same way and expire entries at expires_at when it is present.

If the merchant supplied a refresh token, AIGW uses it. If the refresh token is missing or the merchant rejects it, AIGW drops the credential and returns 410 with msgCode: reauthentication_required. The user must authorize again; AIGW does not re-assert the old login.

Errors

StatusWhenRecovery
400A required header is missing or malformed, or the exchange configuration is unsupportedSend both headers. Check msgCode and msg, and that your proxy or framework is not stripping custom headers.
401User or proxy authentication failed, the user token lacks ext_token:read, the Proxy client was revoked, or the two tokens belong to different ProjectsUse the user's AIGW access token, not an ID token. Use a Proxy client from the Resource's Project and request a new Proxy token.
404The Resource indicator or Project is wrong, or no credential is cached for this loginCopy the indicator exactly. If it matches, inspect provisioning events: the merchant authorization server may have rejected AIGW at sign-in. See Troubleshooting.
410reauthentication_required. The merchant refresh token is missing or was rejectedSend the user through authorization again. Retrying redemption will not help.
500A service or downstream failureInspect Resource events and retry with bounded backoff.

If the agent's AIGW token itself has expired, your own validation rejects it before you redeem. Return 401 to the agent with your WWW-Authenticate header. Log status, msgCode and msg, never the tokens.

Revocation and cleanup

There are two revocation endpoints. They do different amounts of cleanup.

EndpointEffect
Core /oauth2/revoke, advertised in discoveryRevokes the token.
POST https://api.aigw.eval.loginid.ai/api/revokeRevokes the token, drops the user's grant to the client and clears the associated cached merchant credentials.

Authenticate with the client authentication method the agent used at registration. For a confidential client_secret_post agent:

Revoke a user's granthttp
POST https://api.aigw.eval.loginid.ai/api/revokeContent-Type: application/x-www-form-urlencodedtoken=<AIGW_USER_ACCESS_TOKEN>&client_id=<AGENT_CLIENT_ID>&client_secret=<AGENT_CLIENT_SECRET>

The response is 200 with an empty body, even for an unknown or already-revoked token. Proxy-client revocation, agent approval and revocation in the Console, and downstream API sessions are separate controls. Revoking a user's grant does not touch them.

Release status

ScenarioStatus
Redemption on a preconfigured Keycloak Resource (private_key_jwt), recorded in an earlier walkthroughSupported
Redemption on a Resource you configure yourselfUnverified
Merchant authorization server using RFC 8693 token exchangeUnverified
Console "Test exchange" buttonUnsupported

The October 17, 2026 recheck covered discovery and registration only. Login did not complete and redemption was not rerun. Until your own Resource is verified, test it with a real end-to-end flow from the Playground pointed at your Resource, rather than the Console's test button.