Authentication overview
How authentication works in Cushy: registration, sign-in, sessions, the built-in identity provider, and the paths to MFA, SSO and password reset.
Cushy ships with a real, built-in identity provider. You can also delegate sign-in to your own OIDC provider (see Single sign-on). This page is the map of the whole authentication surface.
Registration creates an organization
Registering at /register creates a new organization and makes you its Owner and first Org Admin in one step. You provide an organization name, your name, a work email and a password of at least 8 characters. Emails are globally unique today, so an address can belong to one organization. The API is `POST /api/auth/register`.
Sign-in and sessions
Signing in with email and password (`POST /api/auth/login`) sets an httpOnly session cookie. If your account has MFA, login instead returns a single-use challenge token that `POST /api/auth/mfa/verify` exchanges for a session. Sign out with `POST /api/auth/logout`, which destroys the session server-side and clears the cookie. If you signed in through your organization's identity provider, signing out also ends the session at the identity provider — so the next person at that browser has to authenticate again, rather than being returned silently to your account. For that to work your IdP administrator must register Cushy's post-logout redirect URL, shown on the Team screen's SSO card; if your IdP does not support single sign-out, only the Cushy session ends. On a shared machine you can also use Sign in as a different SSO user on the login page, which asks your identity provider to re-authenticate instead of reusing the session it already holds.
Who am I
`GET /api/auth/me` returns the current user, including the effective capability set. The console uses exactly this to decide which controls to show; the API enforces the same capabilities regardless, so hiding a button is a convenience, not the security boundary.
Related guides
- Multi-factor authentication — enroll TOTP, recovery codes, and disable MFA.
- Single sign-on with OIDC — delegate login to your identity provider.
- Directory sync (pull) — read your IdP on a schedule so users appear without signing in (Keycloak).
- Password reset — the emailed reset-link flow.
- Login protection — the 5-attempt lockout.
Every authentication response is written so that it does not reveal whether an email is registered. See Security model.