Skip to main content

Troubleshooting

Find the failing step below, then check its credentials, configuration, and error response.

Agent cannot complete authorization​

Check: Project → Agents. A newly registered agent may be Pending, Rejected, or Revoked. The system default approves every agent, so if an agent is held or rejected, check Agents → Approval rules (Project default and per-Resource overrides) and KYA issuers; the Decided by column shows whether policy or a person made the decision. See Agent policy.

Also verify redirect URI, PKCE state/verifier, requested scopes, and that the Resource authorization endpoint (not only the core endpoint returned in some DCR metadata) is being used.

DCR fails​

Check:

  • every redirect URI is absolute HTTPS;
  • no unsupported Resource scope is sent in the registration body;
  • grant_types/response_types match the supported OAuth flow.

Agent gets a token, but MCP/UCP redemption fails​

Check:

Missing required redemption headers return 400.

Keycloak returns invalid_client​

Likely causes:

  • client authenticator is not Signed JWT;
  • signature algorithm is not ES256;
  • Keycloak cannot fetch the Resource JWKS URL;
  • Client ID differs between AIGW and Keycloak;
  • client assertion has expired, or its age since iat exceeds Keycloak's configured Max expiration.

Review the Keycloak guide.

Keycloak returns invalid_grant​

Check:

  • JWT Authorization Grant IdP issuer matches the AIGW Resource issuer;
  • JWKS URL is the Resource JWKS;
  • the IdP is allowed on the client;
  • assertion audience matches the realm issuer or its configured custom audience mapping;
  • the asserted sub resolves to a Keycloak user/federated identity;
  • scope configuration is valid.

For a newly created IdP, link the test user, then retry with that same AIGW sign-in identity.

Merchant access token is missing after successful sign-in​

Successful sign-in does not guarantee that the merchant authorization server issued a token. Check the Resource’s Events for the token-acquisition failure, then verify the merchant grant, client authentication, scopes, and user mapping with the merchant IAM administrator.

Scope missing from Keycloak token​

For the Keycloak configuration in this guide:

  • create the client scope with Type None;
  • turn Include in token scope On;
  • attach it to the AIGW client as Optional;
  • keep the scope name identical to the AIGW Requested scope.

Wrong issuer/JWKS used​

Remember the split:

Configuration saved, but the integration does not work​

An Active Resource indicates complete configuration. It does not prove that the merchant accepted an assertion or issued a token. Complete authorization, retrieve the merchant access token, and call the API; use Resource Events to locate the failure.

For merchant-token provisioning, choose private_key_jwt or token_exchange and configure the corresponding merchant grant. Standalone client_secret_basic support for merchant-token provisioning is Coming soon. If the Resource has no active signing key, create one, then verify that its kid appears in the Resource JWKS before retrying authorization.

Credential expiry requires reauthorization​

When credential redemption returns 410 / reauthentication_required, start a fresh user authorization. AIGW does not re-assert an old login when the merchant refresh token is missing or rejected. A 404 can mean no merchant credential exists for this Project/user/Resource/login combination; inspect the Resource's exchange events.

Evidence for a failure report​

Record environment, timestamp/timezone, Resource/client IDs, failing step, HTTP status, and sanitized error code. Resource Events distinguishes sign-in success from exchange/refresh success. Remove bearer tokens, client secrets, authorization codes, login challenges, flow handles, and personal data before sharing traces.