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 these claims:

{
  "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
  "plan": "premium",             // Optional: User's subscription plan
  "features": ["feature1"],      // Optional: Enabled features
  "exp": 1672531199,             // Expiration timestamp
  "iat": 1672444800,             // Issued at timestamp
  "kid": "sso-key-2025-01-01"    // Key ID for key rotation
}

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.