Identity

Every org needs a way to authenticate its members. Swarmfile gives you one out of the box and lets you layer on enterprise identity - SSO, SCIM, and on-prem LDAP sync - as your org grows.

Built-in identity provider#

Every org gets Swarmfile's own OpenID Connect identity provider by default, with email/password authentication. There's no setup required - it's active from the moment your org exists, and for most Starter-plan teams it's all you need.

Bring your own SSO (OIDC)#

Plan: Pro and above.

If your org already runs an identity provider, you can configure it in Swarmfile instead of - or alongside - the built-in one. Owners set it up under Settings → Identity: an OIDC issuer URL plus the audience/client id, validated against your IdP's standard /.well-known/openid-configuration discovery document and JWKS. Entra ID and Okta are the two explicitly supported and tested patterns via their own OIDC endpoints. SAML SSO is offered on Enterprise through an adapter that sits between your SAML IdP and Swarmfile's sign-in, rather than as a self-serve option on this screen; if your IdP only exposes a SAML app, talk to us and we'll set it up with you.

SSO configuration is per-org, and each org's config is hard-bound: when a member signs in, the token they present is validated against the JWKS for that org's specific configured issuer. One org's SSO setup can't be used to forge identity into another org, even if both orgs use the same upstream IdP vendor.

If an external IdP config is ever misconfigured badly enough to lock everyone in the org out, the owner has a break-glass path back to the built-in Swarmfile IdP. This is an owner-only safety net - don't rely on it as a routine way to bypass SSO.

Desktop app: connecting the desktop app works from an external-IdP (SSO) sign-in too. Swarmfile records the external principal - scoped to that issuer and subject - the first time it sees a verified sign-in, and the device session it then mints is marked as externally originated, so your org's authentication policy exempts it exactly like the SSO browser session it came from. Sign in through SSO in the browser, then use Connect app as usual. A subject that collides with an existing Swarmfile account is refused with identity_conflict rather than being merged.

By default, SSO only authenticates people who are already members - someone who signs in successfully via your IdP but isn't yet in the org still needs a manual invite. To skip that step, set an auto-provisioning group in the org's SSO configuration: anyone whose token carries that group in its groups claim is added to the org automatically as a member the first time they sign in. Leave it unset and nothing changes from the default invite-based flow.

If your org's authentication policy requires MFA, you can also give the SSO config an MFA authentication context: Swarmfile sends that value as acr_values on the sign-in redirect so your IdP can ask for an MFA-strength authentication. Ask your IdP which value it accepts (for example urn:mace:incommon:iap:silver); leave it blank to send none - an IdP that validates acr strictly would reject a value it doesn't know, and enforcement at org access is unchanged either way.

SCIM provisioning#

Plan: Pro and above.

SCIM 2.0 lets your identity provider push directory sync - creating and disabling principals, syncing group membership - into Swarmfile directly. SCIM by itself doesn't grant org access: a synced user still needs either an SSO auto-provisioning group match (above) or a manual email invite to actually join the org.

Owners manage it under Settings → Directory Sync: mint a bearer token for the integration (shown once - copy it into your IdP immediately), revoke one, and watch the recent sync log to confirm users and groups are actually arriving. Point your IdP at the hub's SCIM base URL for your org, https://<hub>/orgs/<org-id>/scim/v2; contact us if you need the exact URL for your deployment. Requests authenticate with the bearer token.

Entra and Okta each use slightly different PATCH conventions for SCIM group and user updates. Swarmfile handles both dialects, so you can point either one at the same endpoint without translation on your end.

On-prem LDAP sync#

Plan: Pro and above.

If your org's directory lives on-prem - LDAP or Active Directory rather than a cloud IdP - you run a sync agent on your own infrastructure (for example, as a Docker container pointed at your AD) instead of connecting a hosted IdP. The agent syncs your directory into Swarmfile's principal directory on your schedule, without your directory ever needing to be reachable from outside your network. Like SCIM, this syncs identity - it doesn't by itself grant org access; members still need an SSO auto-provisioning group match or a manual invite.

Authentication policy (require MFA and/or a verified email)#

Plan: Starter and above.

Individual members can always protect their own account with an authenticator app (TOTP), under Settings → Account → Security. An org can additionally require that protection for everyone. Owners configure this under Settings → Identity → Authentication policy:

• Require multi-factor authentication - members must sign in with an authenticator app. A session signed in before enrollment does not satisfy it; sign in again after enrolling.
• Require a verified email address - members must have verified their email before using the org.

You choose when enforcement begins: immediately, or after a grace window (7 days by default; the dashboard offers up to 30 days, and the API accepts up to 3650 days or an explicit enforcement date up to ten years out). During the window everyone keeps working; the web dashboard, the desktop tray, and swarmfile status all nudge members to enroll. Once enforcement begins, any org-scoped request from a session - or a personal access token, which snapshots its session's factors at mint time - that doesn't meet the policy is refused with one clear message and a link to Account settings. Members signing in with a Swarmfile password at the org's login page (/login/<slug>) also see the requirement stated up front, so nobody starts a sign-in without their authenticator; members signing in through the org's own SSO provider are exempt from the policy, so no hint is shown on the SSO button.

Members who would fail also get an email: when the policy is enabled, again in the last 24 hours before enforcement begins, and once it takes effect. These are transactional security notices tied to the org's policy, not marketing - they aren't subject to notification quiet hours or unsubscribe settings.

The refusal is never a lockout: enrolling and verifying are never gated by the policy, and the owner can turn it off at any time from the same Identity page. That off-switch is a genuine break-glass - it stays reachable even for the owner's own non-compliant session.

One gate applies to turning it on: the owner must have enrolled an authenticator app themselves before requiring MFA for everyone - the same rule the org enforces, applied to the person setting it. (Signing in through an external IdP exempts you, since your IdP owns that factor.) Once a policy exists, the Identity card also shows an enrollment summary: how many members are enrolled, and which owners and admins aren't yet. Download CSV beside it exports the full roster - email, name, role, and enrollment status - for an IT review.

If a member loses both their authenticator app and their recovery codes, an operator can remove MFA for them after verifying who they are - the same effect as the member's own Turn off under Account settings: every session is signed out, and the change is recorded in the operator audit trail.

Who's covered:

• Members and owners, including the owner who enabled it. Owners are held to their own policy; only the off-switch is exempt.
• Guests are exempt - a guest's access is limited to the folder they were invited to.
• Project API keys are exempt - they're org-provisioned machine identities, governed by key scoping and revocation.
• Orgs that sign in through their own IdP are exempt from both flags (see Bring your own SSO) - that IdP owns factors and email assertions.

Downgrades follow the same freeze rule as SSO: an enforced policy keeps working if the org drops below Starter, and can always be turned off, but a new requirement can't be turned on until the org is back on Starter or above.

Personal access tokens#

Interactive sign-in is the right thing for a person at a keyboard. It's the wrong thing for a script, a scheduled job, or a CLI session that needs to keep working without a browser in the loop. A personal access token (PAT) is a long-lived bearer credential for exactly those cases - it stands in for you, non-interactively.

The key property is that a PAT carries no permissions of its own. It resolves to your identity, and every access check then runs against your own current role, exactly as if you'd signed in normally. A PAT can never do more than you can do right now, and it stops working the moment your access does: change your role and the token follows it; get removed from the org and the token is invalidated along with your membership. There's nothing separate to clean up.

Because it acts as you and dies with your access, minting one is self-serve for any member - it isn't owner- or admin-gated. Create and revoke tokens under Settings → Access Tokens in the web dashboard. Each token is shown in full exactly once, at creation; after that only its name and prefix are visible. You can hold up to 20 active tokens per member, per org at a time - the cap is counted against your own tokens in that org, so one member's tokens never consume another's allowance. Revoke one to make room if you hit the cap. Tokens can be given an expiry at creation or left non-expiring for unattended automation; the credential begins with an sf_pat_ prefix and is sent as a normal bearer token.

If your org mandates external SSO, PATs are subject to that too - there's no bypass. A token that would authenticate as your built-in identity is rejected in an SSO-enforced org just as an interactive built-in sign-in would be. A PAT is a convenience for your own access, never a way around org policy.

If your org enforces an authentication policy, the same no-bypass rule applies, with one deliberate nuance: a PAT snapshots the factors and email assertion of the session that minted it. A token minted from a compliant session keeps working; a token minted before you enrolled (or before your email was verified) stops satisfying the policy when enforcement begins. Re-sign in with your second factor and mint a fresh token - the Access Tokens page flags any token that won't satisfy the org's current policy.

Security guidance. A PAT is a live credential - treat it like a password. Give each one a descriptive name so you can tell them apart, scope them to a single machine or job rather than reusing one everywhere, set an expiry where the workflow allows, and revoke a token the instant it's no longer needed or might have leaked. Revoking a token from the list ends its access; token material can only ever be created from an interactive sign-in, so revoking every token you can see genuinely ends non-interactive access under your identity.

PATs vs. project API keys#

A PAT is not the same thing as a project-scoped API key, and the difference matters:

• A PAT is you, self-served, org-wide within your own access, and tied to your membership.
• An API key is a separate service identity scoped to a single project, minted by an admin or owner rather than by the member who runs the automation. It has no role of its own beyond that project and doesn't come and go with any one person's membership.
• Keys are a capped plan resource; PATs aren't. Each plan includes a fixed headless-key allowance (Free 1; Starter 2 per seat, min 5; Pro 5 per seat, min 10) and extra capacity comes in 10-key packs ($20/month for 10, either plan); minting past the allowance is refused with keys_cap until a key is revoked or a pack is added. Use PATs for a person's own automation and keys for the org's machines - one key per machine or fleet is the recommended shape, for revocation radius and its own rate-limit bucket (see Billing & Plans).

Revocation takes effect within seconds. Both credentials are checked on every request; revoking a PAT or an API key (or deleting its project) ends its access immediately on the server that handles the revoke, and everywhere else within a few seconds. Revoking a credential also rides Swarmfile's durable revocation sweep, which closes its live event connections - a project API key's own; for a PAT, every live connection for that member, because a connection doesn't name the token that opened it (engines reconnect within seconds with any other valid credential). An org can cap how long one connection may live at all - 5 minutes to 24 hours under Settings → Organization - so a connection can never outlast a missed sweep by more than that cap. A changed per-key rate limit applies on the same schedule.

Reach for a PAT when a job should run as a specific human; reach for a project API key when a CI pipeline or service should have its own durable identity independent of any individual. API keys are covered in Runner as CI and the CLI reference.

Plan gating and what happens on downgrade#

SSO, SCIM, and LDAP sync are all Pro+ features, and the restriction is enforced server-side - not just hidden in the UI. Calling an SSO, SCIM, or LDAP endpoint on a Starter-plan org returns a real 402 rejection, not a silently-ignored request.

Downgrades don't retroactively break things. If an org drops below Pro while SSO or SCIM is already configured, the existing configuration keeps working - turning it off automatically would strand people mid-login or silently break provisioning. The gate only applies going forward: on a Starter plan, you can't set up something new, but nothing already running gets switched off underneath you.

For plan comparisons and pricing, see Billing & Plans. For what an authenticated member can actually access once signed in, see Permissions. Setting up SSO with an auto-provisioning group before you push installers to a fleet removes the separate invite step for newly provisioned employees - see Deploying to Your Team.