Single Sign-On

Single sign-on (SSO) lets the people in your organization sign in to apistash with their existing workplace credentials, through your own identity provider — the same login they use for email and other company tools. It is available on the Enterprise plan.

With SSO set up, a member simply enters their work email on the sign-in page and is handed off to your identity provider. New team members can have their apistash account created automatically on their first sign-in, and the organization roles they receive can be kept in step with the groups your identity provider already manages.

What you get

• Sign in with a business email. Members type their work email and are redirected to your identity provider to authenticate — no separate apistash password to manage.
• Automatic account creation. When someone from your organization signs in for the first time, apistash can create their account and add them to your organization with a default role you choose. You can also require an existing invitation instead. Accounts created this way are managed by your organization: they sign in only through your identity provider, belong only to your organization, and have no password and no standalone personal workspace — your organization stays in control of the account for its whole lifetime.
• A single, enforceable sign-in path. You can require everyone on your verified domains to sign in through your identity provider, so access follows the same policies as the rest of your company tools. (The organization owner can always sign in with a password, so you can never lock yourself out.)
• Roles that follow your directory. Map the groups from your identity provider to apistash organization roles. Every time a member signs in, their SSO-assigned roles are brought back in line with their current group membership.

Setting it up

SSO is configured from Organization → Settings → Single Sign-On. There are three parts: verify your domains, connect your identity provider, and (optionally) map groups to roles.

1. Verify a domain

Add each email domain your members use (for example example.com). apistash gives you a DNS TXT record to publish for that domain; once it is in place, click Verify. Verifying a domain proves your organization controls it, so that only your identity provider can sign in the people who use those email addresses. A domain can be verified by only one organization.

apistash re-checks verified domains periodically. If the DNS record goes missing, single sign-on for that domain is paused. Members who linked an existing password account fall back to normal password sign-in, so a DNS hiccup never locks them out. Organization-managed accounts have no password by design — they sign in again as soon as the record is restored. A deactivated account can be reactivated while its SSO connection is present and enabled. Your claim on the domain is kept the whole time: no other organization can take it, and as soon as the record is back in place the domain re-verifies automatically (or you can click Verify to restore it at once). A domain is only released when you remove it yourself.

2. Connect your identity provider

apistash connects to any identity provider that supports OpenID Connect — including Microsoft Entra ID, Okta, Google Workspace, and Keycloak. You will need, from your provider:

• the issuer URL,
• a client ID and client secret for a confidential application, and
• the redirect URL shown on the settings page, which you register with your provider.

If your provider sends group information under a claim other than groups, set the matching groups claim name — a claim of your provider's own. Standard OpenID Connect claim names (email, sub, name and the rest) are rejected when you save: groups are never read from them, so accepting one would leave group mapping quietly doing nothing on every sign-in.

Allowed groups narrows who may sign in at all. Leave the list empty and everyone your provider authenticates is let through; name one or more groups and everybody else is turned away, whatever their domain says. Group names are matched exactly as your provider sends them, so paste them rather than retyping — a directory that reports CN=Engineers,OU=Groups,DC=example,DC=com has to be entered that way, in full. This is a separate question from Map groups to roles below: the allowlist decides who gets in, the mapping decides what they may do once they are.

The same applies to names. apistash reads the standard OpenID Connect given_name and family_name claims; if your provider publishes them under different keys, set the given name claim and family name claim to match. You can point them at another standard name claim (name, nickname, preferred_username, middle_name) or at a claim of your provider's own. A claim that could never hold a name — email, sub, address and the like — is rejected when you save, rather than accepted and then quietly ignored. Get this wrong and sign-in still works, but accounts are created without a name — and emails to those members then greet them without one. They are two separate settings on purpose: which part of a name is the family name is something your directory knows and apistash would only be guessing at.

It does not matter whether your provider puts these claims in the ID token or serves them from its user-info endpoint — apistash looks in both. Names are read when someone signs in for the first time, so a member created before the claim settings were right keeps the name they were created with.

The settings page also has toggles for the access controls described above:

• Enabled — turn sign-in through this provider on or off. Turning it off blocks new SSO sign-ins; it does not deactivate anyone's account.
• Automatic account creation — create organization-managed accounts on first sign-in, with a default role.
• Link existing accounts — connect a matching password account to its identity on the first SSO sign-in.
• Require single sign-on — members on your verified domains must use SSO.

Replacing your identity provider

Rotating the client secret is an ordinary edit. Changing the issuer URL or client ID, however, moves your organization to a different provider (or a rebuilt one), and providers identify each person by their own internal subject — so every linked sign-on identity must be re-established. apistash treats this as an explicit, confirmed step: the settings page first shows you every affected member and asks you to confirm the re-link. Each member's identity is then re-established automatically at their next sign-in, provided the email your new provider asserts exactly matches their apistash account email. Correct any mismatched addresses before you switch — a member whose emails differ cannot sign in until they match.

Deleting the connection outright is refused while organization-managed accounts exist (active or deactivated) — they could never sign in again. Deleting it also erases the record of previously removed members' sign-on links, so a returning member would link anew through an invitation.

3. Map groups to roles (optional)

Add mappings from an identity-provider group name to an apistash organization role. When a member signs in, apistash reads the groups in their token and grants exactly the roles their groups map to — adding new ones and removing ones they no longer qualify for. Roles you assign to a member by hand are left untouched. A mapped role, on the other hand, only stays gone once the mapping does: take one away by hand while the member's group still grants it and their next sign-in restores it. You can only map roles whose permissions you yourself hold, and the organization owner role can never be mapped.

Managed accounts: deactivating and reactivating

Members whose accounts were created by SSO are managed by your organization, and removing one is a full account deactivation rather than a plain membership removal. Deactivate account (on the member page, for administrators who can remove members) removes the member's roles and team memberships and revokes their sessions, API keys, and authorized OAuth access. Subsequent requests are denied; requests already authenticated and authorized may finish. Their sign-on identity and data are kept, disabled, and their email address stays reserved, so nobody can recreate an account in their name — not even through a fresh SSO sign-in.

A deactivated managed account can be reactivated by an administrator who can invite members (it counts against your seats again). Reactivation restores plain membership with your connection's current default role — previous roles, team memberships, and credentials stay revoked — and the person signs in again through your identity provider, picking up their current group-mapped roles. Reactivation needs the SSO connection to be present and enabled.

Removing a member who linked an existing personal account is different: their account, other organizations, and unrelated credentials stay intact, but their sign-on link to your organization is disabled so a later SSO sign-in cannot silently re-join them. Inviting them back re-enables the link when they accept.

Good to know

• SSO is an Enterprise feature, and each plan includes an allowance of verified domains.
• Group mapping keeps a member's organization roles in sync. Team membership stays a deliberate, manual decision.
• apistash learns about your directory only when someone signs in — OpenID Connect carries no "user was disabled" push signal. Blocking a person in your identity provider stops their next sign-in; to block subsequent requests using existing access, use Deactivate account (managed accounts) or remove them from the organization (linked personal accounts). There is no automatic directory synchronization.
• If you turn on Require single sign-on, also turn on Link existing accounts — otherwise members who joined before SSO was set up have no way to connect their account on their first SSO sign-in, and (being required to use SSO) can no longer use a password either. The organization owner is always exempt and can still sign in with a password. Organization-managed accounts never have a password to fall back on; their sign-in path is the identity provider, repaired or reactivated by an administrator when needed.