Troubleshooting#

Errors organized by step, with causes and fixes.

---

Registration#

Login required#

Fix: Select the built-in Todo resource, complete Step 1 (Login), then come back and click Register custom resource.

Health check failed / timed out#

The wizard checks your server's health before registering. It fails when:

• Your server isn't running
• The health endpoint path differs from the default (/health)
• Your server doesn't respond within 5 seconds
• CORS blocks the browser request

Fix:

1. Confirm the server is running: curl https://your-resource.example.com/health
2. Change the health endpoint path in the wizard if needed
3. Click Connect Anyway to skip the check if CORS is blocking but your server is reachable

Discovery failed (Own Auth Server)#

The wizard tries {issuer}/.well-known/oauth-authorization-server (RFC 8414), then falls back to {issuer}/.well-known/openid-configuration. Both failed.

Fix: You can proceed without discovery — the wizard falls back to {issuer}/token. If that path is also wrong, re-register after adding a discovery endpoint to your auth server.

---

Step 1: User Authentication (SSO)#

Popup blocked#

Fix: Allow popups from this origin in your browser's address bar, then retry.

Popup closed before completing#

Fix: Click Login via IdenX again.

ID token expired before Step 2#

ID tokens expire in ~10 minutes.

Fix: Click Log in again in Step 1's panel. This clears the token chain without losing your resource connection.

---

Step 2: Token Exchange#

invalid_target#

The IDP couldn't find a resource connection for your client and the requested resource URL.

Fix: Clear the resource and re-register using the wizard. It creates the client with the correct resource_connections automatically.

invalid_scope#

The requested scopes aren't permitted for this resource connection.

Fix: Re-register and add the missing scope in Wizard Step 3 (Scopes & Endpoints).

invalid_client#

Client authentication failed. The client ID or secret is wrong, or the client was deleted.

Fix: Check your credentials, or register a new client via Client Registration and reconnect.

token_expired (ID Token)#

Fix: Re-login. See ID token expired.

---

Step 3: JWT Bearer Grant#

invalid_grant: Playground Auth Server#

invalid_grant: Own Auth Server#

Your auth server rejected the ID-JAG. Checklist:

1. Trust the playground IDP's JWKS: https://idp.xaa.dev/jwks (issuer: https://idp.xaa.dev)
2. Accept typ: oauth-id-jag+jwt in the token header
3. aud must match your auth server's issuer URL exactly; watch trailing slashes
4. client_id in the ID-JAG must match a client registered at your auth server. Set this as Target Client ID in Wizard Step 2.

Expand the decoded ID-JAG in Step 2's panel to verify all claims.

invalid_client: Step 3#

Most common cause for developer-registered clients: using the IDP client_id / client_secret (Steps 1–2) instead of the resource_client_id / resource_client_secret (Step 3). These are different credentials. See Why two clients?.

Retrieve the correct resource client credentials from your app card: go to Client Registration, find your app, open the Integration Guide, and reveal the Step 3 secret.

For Playground Auth (other causes): Re-register via the wizard.

For Own Auth Server: Click Change Resource and re-enter the correct Auth Server Client ID and Secret.

Token endpoint not found (Own Auth Server)#

Fix: Ensure your auth server exposes /.well-known/oauth-authorization-server (RFC 8414) or /.well-known/openid-configuration with a token_endpoint, then re-register the resource.

---

Step 4: API Call#

401 Unauthorized#

Your server rejected the token. Work through this checklist:

1. Issuer: iss in the decoded access token (Step 3 panel) must match your middleware's issuer config exactly: https://auth.resource.xaa.dev
2. JWKS URI: your middleware must fetch keys from https://auth.resource.xaa.dev/jwks
3. Audience: aud is your resource URL with a trailing slash (e.g. https://your-resource.example.com/). Match this exactly if you validate audience.
4. Other causes: wrong algorithm (must be RS256), server clock skew, or middleware not running on this endpoint

403 Forbidden#

Token is valid but access was denied. Check the scope.

1. Check the scope claim in the decoded access token. Does it include the required scope?
2. Scopes are space-separated: "files.read files.write". Do not split on commas.
3. Scope names are exact: files.read ≠ files:read ≠ read:files

CORS error#

The browser can't reach your server because it doesn't allow cross-origin requests from the Demo's origin.

Option A: Allow the playground origins (https://xaa.dev and https://app.xaa.dev) on your server. See REST API Setup for code examples.

Option B: Enable Proxy Mode in Step 4. The API call routes through the playground's proxy with the Bearer token forwarded unchanged, so no CORS setup is needed on your server.

Network error / timeout#

1. Is your server running? curl https://your-resource.example.com/health
2. Is the URL correct (right port, no typo)?
3. Is your server listening on 0.0.0.0, not just 127.0.0.1?

---

Session and credentials#

Credentials lost after closing the browser#

Session storage (where the flow stores tokens in-flight) is cleared when the tab closes.

Client credentials are persistent. Retrieve them any time from Client Registration: click Reveal next to Client Secret on your app card, or open the Integration Guide and use the eye icon on any secret row.

Need to re-enter credentials#

Click Change Resource in the resource banner. When you reconnect the same resource, the credential modal reappears.

---

Still stuck?#

Check the Error Codes reference for a full list of error responses and their meanings.