Skip to main content

Handle the callback

After successful user authorization, AIGW redirects to the registered agent callback.

Example:

https://agent.example.com/callback?code=<AUTHORIZATION_CODE>&state=<STATE>

1. Validate state​

Compare the returned state to the value stored for this browser transaction. Reject mismatches and handle OAuth callback errors before attempting a code exchange. If the callback includes iss, compare it exactly with the trusted issuer saved for this transaction. If discovery advertises authorization_response_iss_parameter_supported: true, reject a callback without iss. Never choose the token endpoint from callback parameters.

2. Exchange the authorization code​

Use the core AIGW token endpoint returned by discovery:

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

grant_type=authorization_code
&code=<AUTHORIZATION_CODE>
&redirect_uri=https://agent.example.com/callback
&client_id=<AGENT_CLIENT_ID>
&client_secret=<AGENT_CLIENT_SECRET>
&code_verifier=<ORIGINAL_CODE_VERIFIER>
&resource=https%3A%2F%2Fmcp.example.com%2Fmcp

The example uses the confidential client_secret_post registration from Register with AIGW. For client_secret_basic, authenticate with Basic instead of posting the secret. For a public none client, omit the secret and retain client_id and the original PKCE verifier. An authorization code is short-lived and single-use; reuse the exact registered redirect URI.

A successful exchange returns HTTP 200 with access_token and its lifetime. On an OAuth error, handle the error before retrying; an authorization code cannot be reused.

3. Store the AIGW access token​

If an ID token is returned, validate it with your OIDC library: signature against discovery's core jwks_uri, exact issuer (including its trailing slash), client audience, expiry, and the saved nonce. Decoding a JWT is not validation, and an ID token is not the MCP/UCP bearer.

The resulting access token is what the agent presents to the MCP/UCP service.

Treat it as a credential

Store the AIGW access token securely and never log it in plaintext.

If a refresh token is returned and your agent needs a longer-lived session, follow the standard refresh-token behavior advertised by discovery and your AIGW policy.

Host distinction​

Read the authorization and token endpoints from discovery:

  • authorization is per Resource: https://api.aigw.loginid.ai/<RESOURCE_ID>/oauth2/auth;
  • token issuance is global/core: https://core.api.aigw.loginid.ai/oauth2/token.
Use discovery

Do not derive one host from the other. Read both endpoints from discovery metadata.

Continue to Call MCP / UCP.

See Token endpoint for complete responses, refresh requests, expiry handling, and error recovery.