Enterprise SSO

Your enterprise customers sign in with their own Okta, Entra or any OIDC or SAML 2.0 identity provider — and set it up themselves, without emailing anyone a certificate.

The shape is three deep, so it is worth naming: we host the service, you run an application on it, and your customer is a company with a directory. An SSO provider belongs to one of your organizations.

1. Declare the identity provider's hosts

Registering one makes our server fetch the provider's discovery document, so the hosts have to be trusted in advance — otherwise sso/register would be "make your server request any URL I name".

1curl -X PATCH "$BASE/v1/auth/settings" \2  -H "authorization: Bearer $SK" \3  -H "content-type: application/json" \4  -d '{"ssoOrigins":["https://bigcorp.okta.com"]}'

Every origin the discovery document resolves to must be listed, not just the issuer. Providers routinely put their token and JWKS endpoints on other hosts — Google's issuer is accounts.google.com while its token endpoint is oauth2.googleapis.com — and registration fails with discovery_untrusted_origin naming the exact URL it refused.

These origins are trusted for SSO endpoints only. They never gain the right to make browser requests against your API.

2. POST /v1/auth/sso/register

An organization owner or admin registers the provider. Publishable key and their session.

1curl -X POST "$BASE/v1/auth/sso/register" \2  -H "authorization: Bearer $PK" \3  -H "content-type: application/json" \4  -b "session cookie" \5  -d '{6    "providerId": "bigcorp-okta",7    "issuer": "https://bigcorp.okta.com",8    "domain": "bigcorp.com",9    "organizationId": "org_…",10    "oidcConfig": { "clientId": "…", "clientSecret": "…",11      "discoveryEndpoint": "https://bigcorp.okta.com/.well-known/openid-configuration" }12  }'

A plain member gets 403 — registering an identity provider decides who can enter the organization, so it takes an owner or an admin.

3. POST /v1/auth/sign-in/sso

Users sign in by email domain.

1curl -X POST "$BASE/v1/auth/sign-in/sso" \2  -H "authorization: Bearer $PK" \3  -H "content-type: application/json" \4  -d '{"email":"someone@bigcorp.com","callbackURL":"https://yourapp.com/"}'

Back comes a url to redirect to. Anyone arriving through that provider joins the linked organization automatically, as a member — the point of enterprise SSO is that staff arrive already belonging somewhere.

SAML

The same registration call with samlConfig instead. The certificate and entry point come from the IdP, so nothing is fetched and no origins need declaring.

Give the IdP administrator your service provider metadata:

GET $BASE/v1/auth/sso/saml2/sp/metadata?providerId=bigcorp-saml

It carries the ACS URL they need, which is ours:

$BASE/v1/auth/sso/saml2/sp/acs/bigcorp-saml

IdP-initiated sign-in works without extra setup — the callback handles both the POST from the IdP and the browser's follow-up GET.

Errors