Authentication Flows

This guide explains the core authentication concepts and patterns used in the AuthOS API, including sequence diagrams for key flows.

JWT-Based Authentication

AuthOS uses JWT (JSON Web Tokens) for stateless authentication with server-side session tracking for revocation support.

JWT Signing Algorithm

All JWTs are signed using RS256 (RSA with SHA-256), an asymmetric signing algorithm. This means:

• The API signs tokens using a private RSA key
• Your backend can verify tokens using the public key from the JWKS endpoint
• No shared secrets are required for token validation

JWT Structure

Every JWT issued by the platform contains essential identity claims. To keep tokens small and secure, ephemeral data like permissions and features are fetched server-side from a high-performance cache.

{
  "sub": "user_id",
  "email": "user@example.com",
  "is_platform_owner": false,
  "org": "organization-slug",    // Optional: Present in Org and Service JWTs
  "service": "service-slug",     // Optional: Present only in Service JWTs
  "exp": 1672531199,             // Expiration timestamp
  "iat": 1672444800,             // Issued at timestamp
  "jti": "unique-jwt-id",        // For session tracking
  "kid": "sso-key-2025-01-01"    // Key ID for key rotation
}

Note: Claims like plan, features, and permissions are intentionally omitted from the token to ensure it remains ~300-500 bytes and to support near-instant permission revocation via the platform’s internal moka cache.

See JWT Structure for a detailed breakdown.

Dual Authentication Architecture

The platform features a dual-architecture authentication system that separates administrative access from end-user authentication.

Flow A: Platform & Organization Admin Login

Purpose: Administrative access to the platform or organization dashboards.

Endpoints: /auth/admin/:provider

OAuth Credentials: Uses the platform’s dedicated OAuth credentials configured in the API’s environment variables.

Token Type: Returns either a Platform Owner JWT or Organization Management JWT.

Flow B: End-User Login (BYOO)

Purpose: End-users authenticate to access organization services.

Endpoints: /auth/:provider

OAuth Credentials: Dynamically selects between:

• Organization’s custom OAuth app (if configured via BYOO)
• Platform’s default OAuth app (fallback)

Token Type: Returns End-User Service JWT.

Sequence Diagram

sequenceDiagram
    participant User
    participant App as Client App
    participant API as AuthOS API
    participant Provider as OAuth Provider (GitHub/Google)

    User->>App: Click "Login"
    App->>API: GET /auth/github?org=acme&service=app
    API-->>App: 302 Redirect to Provider
    App->>Provider: Authorize Access
    Provider-->>User: Grant Consent Page
    User->>Provider: Approve
    Provider-->>API: Callback with Code
    API->>Provider: Exchange Code for Token
    Provider-->>API: Access Token / User Profile
    API->>API: Create/Update User & Session
    API-->>App: Redirect to Callback with JWT
    App->>User: Logged In

Flow C: Password Authentication

Purpose: Traditional username/password authentication without OAuth, supporting both platform-level and organization-scoped logins.

Endpoints: /api/auth/register, /api/auth/login, /api/auth/forgot-password, /api/auth/reset-password

Features:

• User self-registration with email verification
• Automatic invitation acceptance on registration
• Secure password reset workflows
• Argon2 password hashing
• Organization-specific SMTP for transactional emails

Flow D: Device Authorization (RFC 8628)

Purpose: Secure authentication for CLIs, smart devices, and headless applications.

Standards: Implements RFC 8628 Device Authorization Grant.

Sequence Diagram

sequenceDiagram
    participant User
    participant Device as CLI / Device
    participant API as AuthOS API

    Device->>API: POST /auth/device/code
    API-->>Device: { device_code, user_code, verification_uri }
    
    par Parallel Execution
        Device->>Device: Display user_code & verification_uri
        loop Polling
            Device->>API: POST /auth/token (device_code)
            API-->>Device: 428 Precondition Required (Pending)
        end
    and User Action
        User->>API: Visit verification_uri
        User->>API: Enter user_code
        User->>API: Login & Confirm
    end
    
    API-->>Device: 200 OK { access_token, refresh_token }
    Device->>User: Login Successful

Flow E: Token Refresh

Purpose: Renew expired access tokens without re-authentication.

Security: Uses refresh token rotation for enhanced security.

Process:

POST /api/auth/refresh
{
  "refresh_token": "current-refresh-token"
}

Important Notes:

• Old refresh token is immediately revoked
• Always store the new refresh token
• Refresh tokens expire after 30 days of inactivity

Flow F: Passkey Authentication (WebAuthn)

Purpose: Passwordless authentication using FIDO2/WebAuthn hardware security keys or platform authenticators (Face ID, Touch ID, Windows Hello).

Standards: Implements W3C WebAuthn specification.

Features:

• Phishing-Resistant: Origin-bound credentials prevent phishing attacks
• Biometric Security: Leverages platform biometrics
• Counter Tracking: Detects cloned authenticators

Flow G: Magic Link Authentication

Purpose: Passwordless authentication via email link, ideal for simplified onboarding.

Security: One-time use tokens with short expiration (15 minutes).

Sequence Diagram

sequenceDiagram
    participant User
    participant App as Web App
    participant API as AuthOS API
    participant Email as Email Service

    User->>App: Enter Email
    App->>API: POST /api/auth/magic-link/request
    API->>Email: Send Magic Link
    API-->>App: 200 OK "Link Sent"
    
    Email-->>User: Receive Email with Link
    User->>API: Click Link (GET /api/auth/magic-link/verify)
    API->>API: Validate Token & Risk Check
    API-->>User: 302 Redirect to App with JWT
    User->>App: Logged In

Bring Your Own OAuth (BYOO)

BYOO allows tenant organizations to use their own OAuth2 applications, providing a white-labeled authentication experience for their end-users.

Organization Setup:

1. Admin creates OAuth app with GitHub/Google/Microsoft
2. Admin configures credentials in AuthOS
3. Secrets are encrypted at rest

End-User Experience:

• Users see organization’s OAuth app name during authorization
• Complete white-labeling of the authentication experience

Session Management

Session Lifecycle:

1. Creation: Session created on successful authentication
2. Usage: Access token valid for 15 minutes
3. Refresh: Use refresh token to get new access token (up to 30 days)
4. Revocation: Sessions can be revoked via logout or admin action

Logout:

POST /api/auth/logout
Authorization: Bearer {access_token}

Multi-Factor Authentication (MFA)

The platform supports TOTP-based (Time-based One-Time Password) MFA.

• Setup: User generates TOTP secret via /api/user/mfa/setup
• Verification: User verifies with code via /api/user/mfa/verify
• Login: After password auth, user must provide TOTP code

Risk Engine & Adaptive Authentication

The platform includes a sophisticated Risk Engine that evaluates login attempts in real-time.

Risk Actions:

See Risk Settings for configuration details.