Best practices

Keep the two tokens apart

Most AIGW mistakes come from a credential ending up in the wrong place. Each party holds only what it needs.

For agent developers

• Start from the 401. Follow the resource_metadata URL in the service's WWW-Authenticate header and read endpoints from discovery. Hard-coded endpoints break when a Resource moves. Discovery reference
• Register once per install, then reuse. Store the client ID and secret in a secrets manager. Registering on every run creates orphaned clients you can't audit.
• Ask for scopes at authorization, never at registration. Request the smallest set the task needs.
• Always use PKCE with S256 and check state. Generate a fresh verifier and state for every authorization request.
• Keep tokens out of the model. The agent runtime attaches the bearer token to HTTP calls; the language model should never see it in a prompt or tool output.
• Handle expiry by re-authorizing. Refresh is unverified in this release, so fall back to a new authorization request when a refresh fails.

For MCP and UCP services

• Validate every AIGW token. Signature from JWKS, iss, aud and exp, on every request. How to validate
• Redeem on the server, keep the result there. Call redemption from your backend and use the merchant token only for the outbound call. Redemption reference
• Send the exact resource indicator. Keep it in configuration, copied from the Console, not assembled from user input.
• Reuse your Proxy token. Cache it for its lifetime and renew it a little before it expires.
• Key users by sub. It is stable and opaque. Don't ask agents for email addresses or names.

For merchant IAM teams

• Trust AIGW through its JWKS URL. Fetching keys by URL lets AIGW rotate keys without a change on your side. Authorization server guide
• Use one identity provider alias per Resource. It keeps audiences unambiguous and lets you revoke one integration without touching others.
• Keep assertion lifetimes short. Use the documented limits: one hour maximum for user assertions, one minute for client assertions, 60 seconds of clock skew.
• Make scopes optional and explicit. Attach agent scopes as optional client scopes so a token carries only what the user approved.
• Decide user mapping first. It is the most common first failure. Pick how AIGW's subject maps to your users before you test.

For everyone

• Redact before you log. Log token IDs, sub, status codes and error codes. Never log full tokens, secrets or ID token contents.
• Retry only what is safe. Retry network errors and 5xx with backoff. Never retry invalid_grant or a used authorization code.
• Build on Supported features first. Check the release status and keep a fallback for anything Unverified.

• Production checklistEvery check to complete before real users and agents arrive.
• TroubleshootingWhat breaks most often, and how to fix it.