Single sign-on for your team

Your team can sign in to the Referalli dashboard with your company's identity provider. There are two ways:

• Your own IdP, directly. Connect OpenID Connect (Okta, Microsoft Entra ID, Google Workspace, Auth0, Keycloak, Ping and others) or WorkOS with your own API key. No broker is involved. This page covers this way.

• The Atlas broker. Send your IT admin a setup link; Atlas runs SAML or OIDC and SCIM, and Referalli follows its directory. Use Settings → SSO → Link for this.

An organization uses one of the two at a time.

Connect OpenID Connect

1. In your IdP, create a web application (confidential client) with the redirect URI:

   https://referalli.com/v1/auth/sso/callback

2. In Settings → SSO → Your own identity provider, choose OpenID Connect and enter the issuer URL, client ID and client secret. The issuer's /.well-known/openid-configuration must be reachable over HTTPS.

3. Save, then Test connection.

4. Share your team's sign-in link: https://referalli.com/v1/auth/sso/start?org=<your org id>.

The same through the API (owner only):

curl -X PUT https://referalli.com/v1/org/sso/direct \
  -H "cookie: referalli_session=…" -H "x-org-id: org_…" \
  -H "content-type: application/json" \
  -d '{
    "adapter": "oidc",
    "issuer": "https://acme.okta.com",
    "clientId": "0oa…",
    "clientSecret": "…",
    "domains": ["acme.com"],
    "roleClaim": "groups",
    "roleMapping": { "referalli-admins": "admin", "finance-team": "finance" },
    "defaultRole": null
  }'

The flow is authorization code with PKCE (S256) and a nonce. The ID token must be signed with an asymmetric algorithm, and its issuer and audience must match. The client secret is encrypted at rest and never returned. To keep the stored secret, leave it out of an update.

Connect WorkOS

Choose WorkOS, then enter your WorkOS client ID (client_…), your organization ID (org_…) and your API key (sk_…). Register https://referalli.com/v1/auth/sso/callback as a redirect URI in WorkOS. Referalli accepts a sign-in only when the WorkOS profile belongs to that organization.

Roles

Referalli reads the person's groups or roles from the claim you name (groups, roles, or a dotted path such as realm_access.roles). WorkOS profiles supply their role and groups. Each value maps to one of admin, finance, analyst or support. When several match, the strongest wins: admin, then finance, then support, then analyst.

• Default role: the role for people whose groups match nothing. Leave it empty to keep them out (sso_no_role).

• Owner is never granted. Neither the mapping nor the default can name it. An existing owner keeps their role whatever the IdP says.

• Roles follow the IdP: each sign-in updates the member's role.

Accounts are never linked by email

A first sign-in from your IdP creates a new Referalli account. If the email address already belongs to an account (for example one that signs in with Atlas), the sign-in is refused with email_taken. It is not linked.

To connect an existing account to your IdP, sign in to Referalli as that account first, then open the sign-in link with &link=1. From then on, the account signs in through your IdP.

Require SSO

List your company's email domains, then turn on Require SSO. Members on those domains must sign in through your IdP. Any other session gets 403 sso_required, with details.signInUrl pointing to your IdP. You can only turn it on from a session that signed in through SSO, so you can't lock yourself out. Removing the configuration turns it off.