Single sign-on API

Tells the entry page how an email address signs in or signs up. sso, required and provider_name are decided by the address's domain alone, against the verified domains of organizations that have an enabled identity-provider connection: sso is true when such an organization holds the domain. required is true when that organization requires single sign-on, which refuses password and passkey sign-in for the domain (createDashboardSession answers sso_required); its break-glass admins keep passkey sign-in. provider_name is the connection's display name, present only when sso is true. account is true when a live person holds the address, verified or not, and false when nobody does: the page signs the person in when it is true and offers signup (POST /api/signups) when it is false and sso is false.

Limited per client address.

Starts a single sign-in through the identity provider of the organization that holds the address's domain and answers the provider's address, which the page navigates to. The response sets the __Host-screenrig-sso cookie (HttpOnly, Secure, SameSite=Strict, Path=/, 10 minutes) that binds this browser to the sign-in.

An OIDC connection is asked for the authorization code flow with PKCE S256, a nonce and response_mode form_post; a SAML connection receives an HTTP-Redirect AuthnRequest.

The provider answers by posting to the connection's /api/sso/oidc/{connection_id}/callback or /api/sso/saml/{connection_id}/acs, and the sign-in ends at /api/sso/finish. return_to is a path under /dashboard/ the sign-in lands on; absent lands on /dashboard/. invitation_token is an invitation the sign-in accepts once the person is signed in. prompt none asks the provider for a silent sign-in, which ends at /dashboard/#sso_error=interaction_required when the person must act; prompt login makes the provider authenticate the person again.

An address whose domain has no enabled connection is not_found. Limited per client address.

The OIDC redirect URI of one connection. The identity provider posts here from another site (response_mode form_post), so no dashboard cookie arrives. The route signs nobody in: it answers a page that posts the same members and the connection id to /api/sso/finish from the dashboard origin, where the transaction cookie arrives.

An answer finishes only a sign-in this connection started; any other ends at /dashboard/#sso_error=bad_state. When the provider's discovery document sets authorization_response_iss_parameter_supported, an answer without iss (RFC 9207) ends at /dashboard/#sso_error=verification_failed.

The page runs one inline script protected by a nonce and carries a noscript button; its Content-Security-Policy is strict, Cache-Control is no-store and Referrer-Policy is no-referrer. An id no connection holds is not_found.

The SAML service provider metadata of one connection. Its entityID is this route's address and its assertion consumer service is /api/sso/saml/{connection_id}/acs with the HTTP-POST binding. An identity provider administrator imports it, or copies the same values from the connection's service_provider. An id no connection holds is not_found.

The SAML assertion consumer service of one connection. The identity provider posts here from another site, so no dashboard cookie arrives. The route signs nobody in: it answers a page that posts the SAMLResponse, its RelayState and the connection id to /api/sso/finish from the dashboard origin, where the transaction cookie arrives.

An answer finishes only a sign-in this connection started. The page runs one inline script protected by a nonce and carries a noscript button; its Content-Security-Policy is strict, Cache-Control is no-store and Referrer-Policy is no-referrer. An id no connection holds is not_found.

Finishes a single sign-in on the dashboard origin, where the __Host-screenrig-sso cookie arrives. The form is state, the connection the answer arrived for, and the identity provider's answer as the callback page copied it: code, error, error_description and iss for OIDC, SAMLResponse for SAML (state is the RelayState).

The route binds state to the cookie, refuses an answer that arrived for another connection than the sign-in started through, verifies the provider's token or assertion, applies the account adoption and linking rules, checks the organization's sign-in policy and answers 303.

A sign-in, renewal or re-authentication mints a dashboard session with auth_method sso, which lasts 24 hours from this sign-in and is not extended by use, accepts the invitation the sign-in carries, sets the __Host-screenrig-dashboard cookie, expires the transaction cookie and redirects to return_to, or to /dashboard/.

A link adds the identity to the signed-in person's account and keeps their session. A test records its outcome on the connection (last_test) and signs nobody in. Every failure also answers 303, to /dashboard/#sso_error=<code>, and never with a problem document.

The codes are no_email, email_unverified, domain_not_allowed, account_exists (the person signs in as before and links from their account), managed_elsewhere, subject_mismatch, not_provisioned, sso_required, staff_account, expired, bad_state, interaction_required (a silent renewal needs the person), provider_refused, provider_unavailable, verification_failed and deactivated (SSOErrorCode).

Starts a single sign-in for the signed-in person and answers the identity provider's address, as POST /api/sso/starts does for an address, setting the __Host-screenrig-sso cookie. intent renew renews a session that signed in through single sign-on, silently (prompt none) before its 24 hours end; the dashboard does so once 12 hours have passed. intent reauth makes the provider authenticate the person again (prompt login), which gives a session the recent sign-in the sso proof needs. intent link attaches the person's identity at the provider to their existing account. renew and reauth need a session that signed in through single sign-on, and link needs an enabled connection at the person's verified domain; otherwise the answer is resource_conflict. return_to is a path under /dashboard/.

A designated admin reads the organization's single sign-on connection: its protocol and provider, the service provider values to enter at the identity provider (the OIDC redirect URI, the SAML entity ID, assertion consumer service and metadata addresses), its sign-in policy and the outcome of the last test.

The client secret is never returned; client_secret_set says whether one is stored. ready_to_require is true once the organization holds a verified domain and a test or a real sign-in has succeeded through the connection's current identity (its issuer, tenant, entity ID and kind); Require SSO is accepted only while it is true. The ETag carries the revision.

An organization with no connection is not_found. Anyone else is refused as on the other organization admin routes. People only; agents and bearer credentials have no route.

A designated admin creates the organization's connection or changes it; an organization holds one.

If-Match carries the connection's revision from GET, or 0 when the organization has none, and is required; a stale value is revision_conflict with current_revision. 201 creates and 200 changes. proof is required: a fresh passkey or password proof bound to a reauthentication of kind identity_provider_change with the organization id as subject_id, or {type: sso} from a session that signed in through single sign-on at most 10 minutes ago (otherwise reauthentication_required).

OIDC with preset entra takes tenant_id and builds the issuer from it; preset generic takes issuer. Omitting oidc.client_secret keeps the stored secret.

For SAML, metadata_xml is read for the identity provider's entity ID, sign-in address and signing certificates, and idp_entity_id, idp_sso_url and certificates_pem state them directly; certificates_pem replaces the stored list, which holds at most 4 so a new certificate can overlap the old during rotation.

While Require SSO is in force a change of identity (issuer, tenant, entity ID or kind) is resource_conflict and certificate and client secret rotation are allowed; outside it, a change of identity makes ready_to_require false until a test or sign-in succeeds. Returns the connection with its ETag. People only; agents and bearer credentials have no route.

Creating the first connection (If-Match 0) is single sign-on, which the Enterprise plan includes; an organization whose plan lacks it is refused with feature_not_in_plan (402).

Changing a connection that exists, such as rotating a certificate or client secret or refreshing metadata, reading, testing and removing one are open on every plan, and a connection that exists keeps signing people in.

A designated admin removes the organization's connection after fresh proof (the body carries proof, as for PUT). It is resource_conflict while Require SSO is in force, scheduled removal included, and not_found when the organization has no connection. People only; agents and bearer credentials have no route.

A designated admin starts a test sign-in through the organization's connection, to prove it works before requiring it. It answers the identity provider's address for the page to navigate to and sets the __Host-screenrig-sso cookie.

The provider's answer ends at /api/sso/finish, which records the outcome on the connection (last_test; a success lets ready_to_require become true) and returns the browser to the dashboard. A test signs nobody in. An organization with no connection is not_found. People only; agents and bearer credentials have no route.

A designated admin turns Require SSO on or off and names the break-glass admins. required true refuses password and passkey sign-in for the organization's verified domains (sso_required) and needs a verified domain and ready_to_require on the connection, otherwise resource_conflict; it bumps policy_revision. required false does not lift the requirement at once: it schedules the removal for 72 hours after the request (enforcement_ends_at) and emails every admin, and DELETE .../sso-policy/removal cancels it. break_glass_user_ids names at most 2 designated admins who hold a passkey, otherwise invalid_request; they keep passkey sign-in while SSO is required, and each such sign-in is audited.

If-Match carries policy_revision and is required; a stale value is revision_conflict with current_revision. proof is required: a fresh passkey or password proof bound to a reauthentication of kind sso_policy_change with the organization id as subject_id, or {type: sso} from a session that signed in through single sign-on at most 10 minutes ago.

Returns the policy with its ETag. People only; agents and bearer credentials have no route. Setting required true is single sign-on, which the Enterprise plan includes; an organization whose plan lacks it is refused with feature_not_in_plan (402). required false is always accepted, and Require SSO that is on stays enforced until it is turned off.

Any designated admin cancels a scheduled removal of Require SSO, so it stays in force. With no removal scheduled nothing changes. Answers the policy. People only; agents and bearer credentials have no route.