Authentication Guide
Understand how SutraID handles authentication, JWT tokens, sessions, and multi-factor authentication.
JWT Tokens
SutraID uses JSON Web Tokens (JWT) signed with HS256 for authentication. Every successful login returns two tokens:
The JWT payload includes a jti (JWT ID) that links to a server-side session. Sessions can be revoked at any time, immediately invalidating the token.
Authentication Methods
Magic Link (Passwordless)
Request a one-time login link sent to the user's email. The token expires after 15 minutes and is SHA-256 hashed before storage. If the user doesn't exist, an account is auto-created on the first magic link request.
Password
Standard email + password authentication. Passwords are hashed with bcrypt (12 rounds). Minimum 8 characters required. Supports password reset via email token.
SSO (SAML 2.0 & OIDC)
Federated login via external identity providers (Okta, Azure AD, Google Workspace, or any SAML/OIDC provider). Supports PKCE for OIDC flows. See the SSO API reference for details.
Multi-Factor Authentication
SutraID supports TOTP-based MFA with backup codes. When MFA is enabled, the login response returns mfaRequired: true with a temporary mfaToken. The client must then call the MFA verification endpoint to complete the login.
MFA Login Flow
1. POST /auth/login → { mfaRequired: true, mfaToken: "tmp_..." }
2. User enters TOTP code from authenticator app
3. POST /auth/mfa/verify-challenge → { accessToken, refreshToken, user }
Body: { mfaToken: "tmp_...", code: "123456" }Role-Based Access Control
Every organization member has a role that determines which API endpoints they can access. The role is included in the JWT payload and enforced server-side.