Authio docs

Authio Lobby

SP-initiated login URL

Point your app's “Sign in with SSO” button at one URL to send a user straight to their identity provider — no Lobby method picker, no extra hop.

Part of Authio Lobby

Authio gives every active SSO connection a stable SP-initiated login URL (WorkOS calls this the “Initiate Login URL”). Hitting it starts a SAML/OIDC service-provider-initiated sign-in: Authio redirects the browser to the customer’s IdP, the user authenticates, the IdP posts the assertion back to Authio’s ACS endpoint, and Authio mints a session and bounces the browser to your redirect_uri.

When to use it vs the hosted Lobby

  • Hosted Lobby (lobby.authio.com) is the method picker — it shows passkeys, Magic Auth, social, and SSO and lets the user choose. Use it for mixed B2C / prosumer sign-in or when you don’t know which org the user belongs to yet.
  • SP-initiated login URL skips the picker entirely. Use it when you already know the user should authenticate against a specific organization’s IdP — e.g. an “Sign in with SSO” button on a tenant-specific subdomain, or an enterprise org with Require SSO turned on.
Pointing your login button at this URL is the WorkOS-style flow: one redirect, no intermediate Authio screen. Because the URL pins organization_id, the Lobby never has to ask “which org?” and never shows the other methods.

URL format

https://sso.authio.com/v1/sso/connections/{connection_id}/initiate
  ?project_id={project_id}
  &organization_id={organization_id}
  &redirect_uri={your_app_callback}

As a single line:

https://sso.authio.com/v1/sso/connections/sso_2x7q/initiate?project_id=proj_abc&organization_id=org_xyz&redirect_uri=https%3A%2F%2Fyour-app.com%2Fauth%2Fcallback

Parameters

  • connection_id — path segment. The SSO connection (sso_…) you’re initiating. Find it on the organization’s Features → Single Sign-On card in the dashboard, where the full URL is also shown with a copy button.
  • project_id — your Authio project (proj_…). Required so Authio resolves the correct tenant and JWKS.
  • organization_id — the org (org_…) the connection belongs to. Strongly recommended: it pins the sign-in to one org so the Lobby never falls back to the method picker.
  • redirect_uri — where Authio sends the browser after a successful sign-in. For SAML SSO this value rides through the IdP round-trip as SAML RelayState and is checked at the ACS endpoint after the user authenticates (see the allow-list note below). The dashboard prefills YOUR_APP_CALLBACK_URL as a placeholder — swap in a real callback URL.
SAML callbacks use a different allow-list than the rest of Authio. Your redirect_uri is not checked against the per-project Settings → Security → Allowed origins & redirect URIs table — that list governs magic-link and OAuth/social callbacks only, so adding your SAML callback there has no effect. Instead, the callback host must appear on the AUTHIO_SAML_ALLOWED_RELAYSTATE_HOSTS allow-list configured on the Authio SSO service. This is a platform/operator setting: if you’re on Authio Cloud, ask your Authio operator to add your callback host; if you self-host, set the env var on the authio_sso service yourself.
The SAML allow-list is matched host-only — scheme + host (lower-cased, port stripped), not a full-URI exact match. Listing app.your-company.com permits any path on https://app.your-company.com. The check runs at the ACS endpoint after the IdP round-trip, not before it.
Symptom of a missing allow-list entry: if the callback host is not on AUTHIO_SAML_ALLOWED_RELAYSTATE_HOSTS, the ACS endpoint does not redirect back to your app. Instead it returns the session envelope — including the access token — as a raw JSON body rendered in the browser. If sign-in succeeds at the IdP but the user lands on a page of JSON instead of your app, the callback host isn’t allow-listed.

Wire it to your login button

// Send the user straight to their IdP (SP-initiated SSO).
const url =
  "https://sso.authio.com/v1/sso/connections/sso_2x7q/initiate" +
  "?project_id=proj_abc" +
  "&organization_id=org_xyz" +
  "&redirect_uri=" + encodeURIComponent("https://your-app.com/auth/callback");

window.location.href = url;

The dashboard generates this exact string for you — open the organization, go to Features → Single Sign-On, and copy the SP-initiated login URL off the connection card. The same URL appears in the post-setup launch checklist and the Settings → Add Authio to your app guide.

Related