Troubleshoot Quick Login

Find the stage that failed before starting another attempt. A successful QR response confirms request creation, not identity approval or application login.

Symptom	What to check
QR request fails	Confirm HTTPS, the Neuron host, `/QuickLogin` availability, JSON content type, and all four required request fields. Inspect the actual HTTP status.
Browser reports a CORS error	The Neuron must allow your page origin, POST, and `Content-Type`. Adding headers to your own page cannot change the Neuron’s CORS policy.
WebSocket fails	Check `wss://<host>/ClientEventsWS`, subprotocol `ls`, allowed origins, and network/proxy WebSocket support.
QR appears but no result arrives	Register the event connection first and use that exact tab identifier in the QR request. Confirm the user approved and that the connection remains open.
App refuses a code	Start a fresh attempt; codes expire after five minutes. Check the app’s supported provider, identity status, and displayed purpose.
Clicking the QR does nothing	Open on a device with a compatible identity app, or scan from another device.
Callback is never reached	Check callback HTTPS reachability, the service registration’s five-minute lifetime, and whether the QR request contains the correct `serviceId`.
Callback completed but the browser still waits	Return valid JSON, even `null`, from the callback. Check `SignatureReceivedBE` delivery and query your backend’s session state.
Backend says the attempt is unknown	Match callback `SessionId` to the original registration’s `sessionId`, including case. Reject expired or reused attempts.
Agent API exchange fails after approval	Browser-only mode does not establish a Neuron session. Use session mode, preserve cookies, and check the account prerequisites.
Embedded reference script crashes or redirects	The deployed script depends on its example page’s filter controls and includes a five-minute redirect. Adapt it to your page lifecycle.

Expiry, cancellation, and retries

Stop refresh timers and close event connections after completion, cancellation, or navigation. Abort pending requests so a late QR response cannot replace a completed result. Use a fresh unpredictable tab identifier for a new attempt, and ignore responses belonging to previous attempts. Closing a tab does not revoke an issued QR. Do not assume the service sends an explicit rejection or cancellation event: the public guide documents success events. Provide a visible waiting state, cancel action, timeout, and retry action in your application.

Session-specific checks

Browser-only requests can work without cookies. Session and session-proxy modes require them. Check cookie storage, SameSite and Secure attributes, credentialed CORS, and whether browser privacy settings block cross-site cookies. A proxy must retain a cookie jar for the Neuron session and bind it to the correct application user.

Diagnose without exposing identities

Record the stage, status code, timing, and connection state. Avoid logging full identity results, QR signing URLs, attachment access URLs, cookies, or tokens. When reporting a provider issue, send a redacted request shape and the exact endpoint and event type involved. Compare with the provider-hosted example to distinguish your integration’s origin or lifecycle problems from service availability.

Start here

Integrate

Reference

Expiry, cancellation, and retries

Session-specific checks

Diagnose without exposing identities

​Expiry, cancellation, and retries

​Session-specific checks

​Diagnose without exposing identities

Expiry, cancellation, and retries

Session-specific checks

Diagnose without exposing identities