Credential redemption

The MCP/UCP service obtains the merchant access token through:

POST https://api.aigw.loginid.ai/api/credentials/token

Request

Authorization: Bearer <AIGW_ACCESS_TOKEN>
X-Proxy-Token: <PROXY_TOKEN>
Content-Type: application/json

{
  "resource": "https://mcp.example.com/mcp"
}

Requirements:

• the user's AIGW access token must have ext_token:read and be associated with a Project and an authenticated login (login_id);
• X-Proxy-Token is the proxy access token without a Bearer prefix;
• the user's AIGW access token and the Proxy token must belong to the same AIGW Project;
• resource is resolved against Resources in that Project;
• it must match the Resource indicator configured on the Token exchange Resource;
• missing required headers return 400.

Token storage and renewal

AIGW requests a merchant access token when the user completes authorization and stores it in the Token Vault for that user’s login, Project, and Resource. Credential redemption returns the stored token and refreshes it when needed.

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

Response and recovery

HTTP 200 OK:

{
  "access_token": "<MERCHANT_ACCESS_TOKEN>",
  "expires_at": "2030-01-01T18:30:00Z",
  "scopes": ["search:read"]
}

Field	Availability	Meaning
access_token	Required	Merchant credential to send from your service to the merchant API
expires_at	Optional	Absolute expiry in RFC 3339 format; omission does not mean unlimited validity
scopes	Optional	Scopes reported by the merchant authorization server

The merchant refresh token is never returned. Use the returned expiry to bound local caching.

Error responses

Credentials from different Projects return HTTP 401 Unauthorized:

{
  "msgCode": "unauthorized",
  "msg": "proxy and token belong to different projects"
}

A merchant credential that cannot be renewed returns HTTP 410 Gone:

{
  "msgCode": "reauthentication_required",
  "msg": "re-authentication required"
}

HTTP status	msgCode	Action
400	bad_request	Check the Resource indicator and request fields
401	unauthorized	Check both tokens, ext_token:read, and their Project association
404	not_found	Verify the indicator and complete user authorization for this Resource
410	reauthentication_required	Run a fresh user authorization; retrying the same credentials will not restore the grant
500	internal_error	Retry with backoff; contact support if the failure persists

These errors contain msgCode and msg. Use msgCode for recovery decisions; message text may vary. Malformed requests or missing required headers can return 400 request-validation errors with a different body. Validate the HTTP status before reading success fields. See retrieval error handling.

Revocation and cleanup

Discovery advertises the core OAuth server's /oauth2/revoke, which revokes the token. AIGW additionally exposes POST https://api.aigw.loginid.ai/api/revoke, which drops the user's grant to the client and clears the associated cached merchant credentials as well. Use the client authentication method from registration.

For a confidential client_secret_post agent:

POST https://api.aigw.loginid.ai/api/revoke
Content-Type: application/x-www-form-urlencoded

token=<AIGW_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/revocation, and downstream API sessions remain separate controls.