Skip to main content

Troubleshooting

Use this page from the failure point outward. The most common problems in the supplied environment were ownership/project mismatches, pending agents, Keycloak JWT trust configuration, scope configuration, and user matching.

Agent cannot complete authorization​

Check: ProjectProjectThe isolation boundary for an integration. It holds Resources, agents and agent policy, end users, and Proxy clients. → 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 rulesApproval rulesThe part of Agent policy that sets Approve, Hold, or Reject for unverified agents and for each kind of agent proof. (Project default and per-Resource overrides) and KYA issuersKYA issuersThe per-Project (or per-Resource) whitelist of KYA credential issuers AIGW accepts, each with a minimum trust level.; the Decided by column shows whether policy or a person made the decision. See Agent policy.

Pending agents

Also verify redirect URI, PKCEPKCEProof Key for Code Exchange: binds an authorization request to the later code exchange so a stolen code is useless. state/verifier, requested scopes, and that the ResourceResourceThe downstream system registered in a Project. Its kind (Token exchange or OAuth client) decides the role AIGW plays. authorization endpoint (not only the core endpoint returned in some DCRDCRDynamic Client Registration (RFC 7591): an agent registers itself as an OAuth client at runtime, with no manual setup. 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:

  • Authorization: Bearer <AIGW token> is present;
  • X-Proxy-Token is present;
  • Proxy clientProxy clientThe server-side credential (client ID and secret) the MCP/UCP service uses to authenticate itself to AIGW. Never give it to an agent. is from the same AIGW Project as the user's token;
  • resource exactly matches the Resource indicatorResource indicatorThe exact identifier (audience) of the merchant API. The MCP/UCP service sends the same value when redeeming the merchant token.;
  • Resource exists in that Project.

The supplied test confirmed that missing 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 JWKSJWKSJSON Web Key Set: a published set of public keys used to verify JWT signatures. URL;
  • Client ID differs between AIGW and Keycloak;
  • client assertion lifetime 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;
  • custom audience mapping exists;
  • the asserted sub resolves to a Keycloak user/federated identity;
  • scope configuration is valid.

The supplied setup identified user linking/mapping as the most likely first failure for a newly created IdP.

Merchant token is missing after successful sign-in​

In the supplied backend, external token provisioning is best-effort during login completion. A failure does not block sign-in. Check backend logs/events for external-token provisioning failures, then test the merchant AS grant independently if possible.

Scope missing from Keycloak token​

For the supplied setup:

  • 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:

  • agent AIGW token → core issuer/JWKS;
  • merchant-facing AIGW assertion → per-resource issuer/JWKS.

Known Console limitations​

As of Console version 0.10.1 / 0.14.1:

  • Test exchange is shown on the Resource but produced no visible result;
  • Connect provider (custom IdP) is still disabled;
  • client_secret_basic for Token exchange now asks for a client secret, but backend notes mark it as not implemented;
  • Domain rulesDomain rulesAgent policy rules that approve, hold, or reject agents from a specific domain and its subdomains. Checked before approval rules. under Agent policyAgent policyProject or Resource rules that approve, hold, or reject an agent the first time it asks for a Resource. The default approves everyone. shows "Not built yet"; some KYAKYAKnow Your Agent: a credential from a third-party issuer that vouches for an agent. issuers are listed as Disabled;
  • End Users (account and project) failed to load with "Couldn't load end usersEnd userA person an agent has acted on behalf of at a Project's Resources, as listed in the AIGW Console.";
  • event logging gaps for some Resource/signing-key operations were observed in an earlier walkthrough;
  • preview/login UI inconsistencies for some identity-provider combinations were observed in an earlier walkthrough.

These are product observations, not protocol requirements.