Troubleshooting
Fix the most common failures, from DCR errors to Keycloak invalid_grant.
Checked against the Evaluation environment, Console 0.10.1 / 0.14.1, on October 19, 2026. Release status
Work from the failure point outward. The most common problems in this release are Project mismatches, Pending agents, Keycloak trust configuration, scope configuration and user matching. Where this page names an error code or status, AIGW or Keycloak documents it; where a cause is not confirmed, it is marked Unverified.
Start from the failing stage
| Stage | Who sees it | Jump to |
|---|---|---|
| Dynamic Client Registration | Agent developer | Registration |
| Sign-in, consent, authorization code | Agent developer | Authorization |
| Code exchange, Proxy token, token validation | Agent developer, MCP/UCP operator | Tokens |
/api/credentials/token | MCP/UCP operator | Credential redemption |
| Merchant authorization server | Merchant IAM administrator | Keycloak |
| Console screens | Project operator | Console |
To isolate a stage, run the same Resource through the Playground. It shows each real AIGW response unmodified.
Registration
| Symptom | Cause | Fix |
|---|---|---|
| Registration is rejected with an HTTPS error | A redirect URI is not an absolute HTTPS URL, or the Playground was opened over HTTP | Register only HTTPS redirect URIs. For local work, use a tunnel. |
| The whole registration is rejected | The body includes a resource scope that isn't registrable for a dynamic client | Remove scope from the registration body and request scopes on the authorization request. |
| Registration fails with valid redirect URIs and no scope | grant_types or response_types don't match the supported flow | Send ["authorization_code", "refresh_token"] and ["code"] with client_secret_post, as in the agent guide. |
Authorization
| Symptom | Cause | Fix |
|---|---|---|
| Authorization is refused right after a successful registration | The agent is Pending, Rejected or Revoked under the Project's agent policy | In Console, open the Project, then Agents. Approve the agent, or check the approval rules (Project default and per-Resource overrides) and KYA issuers. The Decided by column shows whether policy or a person made the decision. |
| Authorization fails although the request looks correct | The agent used a core endpoint returned in registration metadata instead of the per-Resource authorization endpoint | Use authorization_endpoint from https://api.aigw.eval.loginid.ai/<RESOURCE_ID>/.well-known/openid-configuration. |
The callback state doesn't match | The callback belongs to a different or replayed transaction | Reject the callback and start a new authorization with fresh PKCE values and state. |
| Requested access isn't granted | The requested scopes aren't configured on the Resource | Request only scopes listed in discovery for that Resource. |
User consent and agent approval are separate. A well-formed request from a held agent is still refused. Check the agent's status before you debug PKCE or the sign-in flow.
Tokens
| Symptom | Cause | Fix |
|---|---|---|
| Code exchange fails | The redirect_uri differs from the registered one, or the code_verifier doesn't match the challenge | Reuse the exact registered redirect URI and the verifier stored for this transaction. |
| Code exchange fails with credentials in an Authorization header | Agents register with client_secret_post. Other client authentication methods at the token endpoint are Unverified. | Send client_id and client_secret in the form body. |
Proxy token request returns 401 | Wrong Proxy client ID or secret, or the Proxy client was revoked | Check the stored values. If the secret is lost, generate a new Proxy client and revoke the old one. |
| Your service rejects AIGW tokens that the agent just received | Validation uses the per-Resource issuer or JWKS | Agent-facing AIGW tokens use the core issuer and JWKS. Read issuer and jwks_uri from discovery. |
| The merchant authorization server rejects AIGW's assertion signature | It trusts the core JWKS instead of the per-Resource JWKS | Configure the Resource's JWKS URI from its Reference screen. Merchant-facing assertions use the per-Resource issuer and keys. |
| Refresh fails | The refresh token flow is Unverified in this release | Run the authorization step again to get a new AIGW access token. |
Credential redemption
| Symptom | Cause | Fix |
|---|---|---|
400 | Authorization: Bearer or X-Proxy-Token is missing | Send the user's AIGW token as the bearer token and your Proxy token in X-Proxy-Token. |
401 | User or proxy authentication failed, the user token lacks ext_token:read, the Proxy client was revoked, or the Proxy client belongs to a different Project than the user's AIGW token | Send the user's AIGW access token, not an ID token, and use a Proxy client from the same Project as the Resource. |
404 | resource doesn't exactly match the Resource indicator, the Project is wrong, or no credential is cached for this login | Copy the Resource indicator from the Resource configuration, character for character. If it matches, inspect provisioning events. |
410 reauthentication_required | The merchant refresh token is missing or the merchant rejected it, so AIGW dropped the credential | Send the user through authorization again. AIGW does not re-assert the old login. |
500 | A service or downstream failure | Inspect Resource events and retry with bounded backoff. |
| Sign-in succeeded but there is no merchant token | Provisioning at sign-in is best-effort. The merchant authorization server rejected AIGW, and sign-in continued without a merchant token. | Check backend events for provisioning failures, test the merchant grant on its own if you can, then work through Keycloak trust and user mapping. |
| Redemption fails only on a Resource you configured | Redemption on a newly configured Resource is Unverified in this release | Confirm the flow on the Playground's default Resource, then compare your Resource and authorization server settings. |
For 400, check msgCode and msg in the body. The full table is in the redemption reference.
Keycloak trust and user mapping
Most likely first failure
For a newly created identity provider in Keycloak, user linking or mapping is the most likely first failure. If the asserted sub doesn't resolve to a Keycloak user or federated identity, Keycloak returns invalid_grant and no merchant token is stored.
Keycloak automatically provisioning users from AIGW assertions is Unverified in this release, so plan for the user to exist or be linked already. Full setup is in Configure your authorization server.
Keycloak returns invalid_grant
| Check | What it should be |
|---|---|
| User mapping | The asserted sub resolves to a Keycloak user or federated identity |
| JWT Authorization Grant IdP issuer | Matches the AIGW Resource issuer |
| JWKS URL | The Resource JWKS from the Reference screen |
| Client settings | The IdP is allowed on the client |
| Audience | A custom audience mapping exists |
| Scopes | The scope configuration is valid |
Keycloak returns invalid_client
| Likely cause | Fix |
|---|---|
| The client authenticator is not Signed JWT | Set the client authenticator to Signed JWT. |
| The signature algorithm is not ES256 | Set the algorithm to ES256, matching the Resource signing key. |
| Keycloak can't fetch the Resource JWKS URL | Make the JWKS URL reachable from Keycloak. |
| The Client ID differs between AIGW and Keycloak | Use the same Client ID in both. |
| The client assertion lifetime exceeds Keycloak's configured Max expiration | Raise Max expiration in Keycloak to cover the assertion lifetime. |
Scope missing from the Keycloak token
- 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 requested scope on the AIGW Resource.
Console
Behavior of Console 0.10.1 / 0.14.1 in the Evaluation environment.
| Item | Status | What to do instead |
|---|---|---|
| End Users list (account and project) fails with "Couldn't load end users" | Known issue | No workaround is documented for this release. |
| Test exchange button on a Resource | Unsupported | It produces no visible result. Test redemption with the Playground's Redeem step. |
client_secret_basic for a Token exchange Resource | Unsupported | The Console asks for a client secret, but the method isn't implemented. Use private_key_jwt. |
| Domain rules under agent policy | Planned | Not available in this release. Use approval rules, or approve agents by hand under Agents. |
| Some KYA issuers listed as Disabled | Planned | Not available in this release. Use the enabled issuers or another agent proof in your approval rules. |
| Connect provider (custom identity provider) | Planned | Not available in this release. Use the identity providers already enabled on your Account. |
| New agents don't appear as Pending | Expected | The default agent policy approves every agent. Set approval rules to Hold to review agents under Agents, then Pending. |
Gaps in event logging for some Resource and signing-key operations, and sign-in preview inconsistencies for some identity provider combinations, were observed in an earlier walkthrough. Both are Unverified for this release.
Paths not verified in this release
If you hit a failure on one of these paths, confirm the same step on a supported path first. These are not known to be broken; they have not been confirmed end to end.
| Path | Status | Supported path to compare against |
|---|---|---|
| Refresh token flow | Unverified | A fresh authorization |
| Token exchange (RFC 8693) to the merchant authorization server | Unverified | private_key_jwt |
| Redemption on a newly configured Resource | Unverified | The Playground's default Keycloak Resource |
| Keycloak user auto-provisioning | Unverified | A user that already exists or is linked |
| Web Bot Auth agent verification | Unverified | Agent policy approval |
| Sign-in with each individual identity provider | Unverified | The providers used in the Playground |
The full matrix is on Release status.
Still stuck
Note the stage, the request you sent with secrets removed, the response status and body, and your Project and Resource IDs. Then contact us.