Troubleshoot Modular SSO

This page lists the problems developers hit most often while adding Modular SSO. Find the error you got in the table, then follow its link for the cause and the fix. You fix most of them in your app or your Scalekit settings; the ones marked IT admin are fixed by your customer’s IT admin in their identity provider (IdP).

For other codes, see the SSO error reference. To see what happened in one login, find it under Logs in the dashboard; see Auth logs.

• On your callback URL. When a login fails at Scalekit or at the IdP, Scalekit redirects the user to your callback URL with error, error_description and your state, instead of a code.
• From the code exchange. The SDK throws an error that carries Scalekit’s JSON response, such as {"error":"invalid_grant","error_description":"invalid code"}. In Node.js, read it from err.response.data; in Python, it’s in the exception’s message. Go by the error value, not the HTTP status.
• On a Scalekit error page. When Scalekit can’t trust the callback URL or the client ID, it can’t redirect the user, so it shows the error itself.

error=invalid_connection_selector
error_description=Need additional details to initiate SSO. Atleast one of: (organization_id, external_id, connection_id, domain).

Cause: Scalekit couldn’t tell which customer’s IdP to send the user to. The authorization URL has no organization ID, connection ID, domain or login hint, or the one it has isn’t in this environment, such as an organization ID copied from development into production, or an email domain that isn’t on any organization.

Fix: Pass one of them when you build the authorization URL, using IDs from the same environment as your API credentials. To route by email, first add the customer’s domain to their organization; see Route users to SSO by email domain.

Scalekit shows this on its own error page, with HTTP status 400:

The requested redirect_uri is missing in the client configuration. If you have any questions, you may contact the administrator of the application.

Cause: The callback URL in your authorization URL isn’t one of the environment’s allowed callback URLs. The match is exact, so http://localhost:3000/auth/callback and http://localhost:3001/auth/callback are different URLs.

Fix: Add the URL under Authentication > Redirect URLs > Allowed callback URLs; see Register redirect URLs. An app served from several hosts, such as one per region or per customer subdomain, needs each callback URL registered.

Cause: Scalekit shows this on its own error page, with HTTP status 400, when the client ID in the authorization URL doesn’t belong to this environment.

Fix: Take SCALEKIT_ENVIRONMENT_URL and SCALEKIT_CLIENT_ID from the same environment, under Developers > Settings > API Credentials.

error=invalid_request
error_description=The scope of your request is missing. Please ensure some scopes are requested. If you have any questions, you may contact the administrator of the application.

Cause: The authorization URL has no scope. The SDK adds openid profile email for you, so this happens when the URL is built by hand.

Fix: Build the URL with the SDK, or add scope=openid profile email.

{"error":"invalid_scope","error_description":"invalid scope offline_access not allowed"}

Cause: The authorization URL asked for offline_access, which requests a refresh token. The login succeeds and the code exchange fails. In Modular SSO your app runs the session, so Scalekit doesn’t issue refresh tokens.

Fix: Remove offline_access from the scopes. When your app’s session ends, send the user through SSO again; see Start your session.

{"error":"invalid_grant","error_description":"redirect_uri does not correspond"}

Cause: The redirect URI you passed to the code exchange isn’t the one you passed to the authorization URL.

Fix: Pass the same URL to both. Keep it in one setting, such as the REDIRECT_URI environment variable the callback guide uses, rather than building it from the incoming request, which can differ behind a proxy.

{"error":"invalid_grant","error_description":"invalid code"}

Cause: A code works once. It was usually already exchanged: the user refreshed the callback page or went back to it, or your app handled the same callback twice.

Fix: Exchange each code once, then redirect away from the callback URL so a refresh doesn’t replay it. If an exchange fails, start a new login rather than retrying the code.

{"error":"invalid_client","error_description":"invalid client_id / client_secret"}

Cause: The client secret doesn’t match the client ID, often because it’s from another environment or was replaced.

Fix: Use the client ID and secret from the same environment. After you generate a new secret, update it wherever your app is deployed.

error=invalid_idp_initiated_sso
error_description=Initiate-login URL is not configured for the environment

Cause: A user started from their IdP’s dashboard, such as an Okta app tile, and your production environment has no initiate login URL. A development environment falls back to a Scalekit page instead, so this often shows up first after go-live.

Fix: Build an initiate login endpoint that accepts a GET request, and register it under Authentication > Redirect URLs > Initiate login URL; see IdP-initiated SSO. Test it with the SSO simulator’s IDP Initiated SSO option. Until it’s live, ask the customer’s users to start from your app’s login page.

Cause: The SAML response doesn’t match a login Scalekit started in this browser. Scalekit tracks each SAML login with a short-lived cookie, which is lost when the app opens the login in an embedded web view, when the user runs two logins at once in the same browser, or when they take several minutes at the IdP.

Fix: Open SSO logins in the system browser, not an embedded web view, one at a time. A user who sees this once can start the login again.

Cause: Scalekit can’t use the IdP’s SAML metadata or signing certificate, so logins for that connection fail. The most common cause is a signing certificate that was uploaded by hand and has expired.

Fix: Your customer’s IT admin uploads the IdP’s current signing certificate, or switches the connection to a metadata URL, which picks up new certificates when the IdP rotates them. See Certificate expiry and rotation.

Cause: The IdP didn’t send an attribute Scalekit needs, such as the user’s email address or, for SAML, a NameID. The error_description names it.

Fix: Your customer’s IT admin maps the attribute in their IdP’s app settings, then checks it with Test Connection in the admin portal.

Cause: The login succeeds, but the profile has no givenName or familyName, so your app shows a blank name or undefined undefined. The IdP sends only the email address.

Fix: Your customer’s IT admin maps the first and last name attributes in their IdP, for example in Okta’s attribute statements, and checks them with Test Connection in the admin portal. In your app, fall back to the email address when the name is empty.

Cause: The portal works for you but is blank for your customer, because their network blocks the files it loads.

Fix: Your customer’s IT admin allows your Scalekit environment’s domain, or your custom domain if you use one, and Google Fonts (fonts.googleapis.com and fonts.gstatic.com).

Find the login under Logs in the dashboard: a failed login has the status Failure and the error details. When you contact support, include the login’s time, the organization ID and the error and error_description values.

• SSO error reference: the error codes your callback can receive and how to resolve them.
• Production readiness checklist: what to check before your first customer goes live.