Troubleshooting integrations
Start with the exact issuer, client ID/type, operation, HTTP status, safe error code and time of failure. Do not include client secrets, passwords, OTPs, recovery codes, authorization codes, cookies or complete tokens in diagnostics.
| Symptom | Check |
|---|---|
| Account Security launch, callback or verification fails | Follow the account-center troubleshooting table. Check environment availability, live server-held user token, callback cookie and one-time pending state; redact all handoff handles. |
| Discovery returns 404 | Copy the entire issuer including /t/<tenant-id>; confirm workspace/application/client are active and the hostname is connected. Add client_id for deterministic metadata. |
| Callback rejected | Exact scheme, hostname, port, path and slash must match registration and code exchange. Confirm state/nonce/verifier belong to this attempt and the code is not expired or consumed. |
| Library reports invalid request | Remove unsupported automatic parameters such as prompt, audience, response_mode, max_age or logout hints. Use the field reference. |
| Confidential token call rejected | Send Basic from the backend, not an Origin-bearing browser request; no body secret. Check secret expiry and matching client ID. |
| Browser CORS failure | Register the exact browser origin for the public client. Permission checks and confidential-client calls are server-only. Do not disable CORS as a workaround. |
| JWT decoder cannot read access token | Access tokens are opaque. Use the server permission check; only ID tokens are verified as JWTs. |
| No email/name in UserInfo | Register/request email profile and start a fresh authorization. Email requires the email scope; name is optional and needs a stored display name. Require explicit email_verified === true when your product needs proof. Never substitute console profile data. |
| M2M client exists but token request fails | Complete the API resource and explicit client grant. Request a nonempty allowed API scope; remove openid and other identity scopes. |
| Login succeeds but API access fails | Check audience/resource, client grant, requested permission, user admission, role assignment and exact organization context. |
| Role change seems ineffective | Do not cache allow decisions or use a previously verified ID token as live API authority. Re-check with the current opaque token. |
| Refresh suddenly stops | Look for concurrent refresh or replay of a superseded token; session, user, policy or grant may also have expired/changed. Restart sign-in; do not loop on the old token. |
| Hosted logout fails after revocation | Hosted logout requires an active grant and session cookie. Use a tested logout sequence rather than revoking first and assuming hosted logout remains available. |
| Magic link fails in another browser | Proof is bound to the initiating browser. Restart there, use an unexpired message and complete confirmation. |
| Recovery code does not replace a lost primary passkey | Recovery codes repair MFA after primary authentication; they do not prove a lost sole primary identity. |
| Passkey disappears on a custom host | WebAuthn credentials are hostname-bound. Use the accepted hostname/enrollment migration; do not weaken relying-party checks. |
| Required SSO denies a member | Check current domain proof, membership, connection, application binding and provider response. Do not enable password fallback to mask required-SSO failure. |
| SAML response rejected | Both Response and Assertion signatures, pinned certificate, immutable NameID, recipient/audience/destination, correlation and time bounds must match. |
| Social/enterprise setup fails despite correct values | Consult the known provider-network follow-up and real-provider acceptance status; do not repeatedly rotate correct secrets to mask an adapter problem. |
| Wrong logo, colors or text after save | Check workspace and Sandbox/Production against the actual issuer. Save the theme there, then start a fresh real flow. Existing pages retain their loaded appearance. |
| Console owner cannot sign in to the product | Administrator and end-user identities are separate. Register or admit an application user under the intended realm and policy. |
| Deployment says a configured secret is missing | Check the running release and its secret-binding allowlist as well as the secret store. Do not print the secret while diagnosing. |
| Hosted page or callback takes too long | Measure entry, form, proof, exchange and bootstrap separately. Remove duplicate discovery/profile work; see performance. Raising timeouts alone does not fix the slow stage. |
| Repeated redirects or old login page in an installed app | Exclude callback/error/signed-out routes from automatic login. Keep auth/bootstrap network-only and update stale service-worker shells. |
| Branding Try looks usable but cannot sign in | It is appearance-only. Start a real flow from your client to test method availability and token issuance. |
| Custom domain resolves but is not Connected | Verify ownership/DCV, certificate and hostname status, DNS-only CNAME target and routing probe. Email-domain proof for SSO is a different process. |
/v1/... or a console catalog endpoint returns unavailable |
Reserved public API families are not released management contracts. Do not reuse private console cookies or bindings from application code. |
For a reproducible report, capture steps, client type, expected result, sanitized request field names, response status/error and any returned decision reference. Identify the browser/OS and which authentication hostname was used. Record provider name and registration category without secrets. Keep the original failure time and timezone so operators can correlate appropriate audit/operational evidence.