API Sequence Diagram

# User Authentication Flow

**API Sequence Diagram Documentation**

This document illustrates the complete authentication flow for our web application, showing the interaction between the client, API gateway, authentication service, and database.

---

## Overview

The authentication system uses JWT tokens with a two-step verification process. Users authenticate via email/password, receive a JWT token, and can then access protected resources.

## Authentication Sequence

```mermaid
sequenceDiagram
    participant User
    participant Client
    participant API as API Gateway
    participant Auth as Auth Service
    participant DB as Database
    participant Email as Email Service

    User->>Client: Enter credentials
    Client->>API: POST /api/auth/login
    API->>Auth: Validate credentials

    Auth->>DB: SELECT user WHERE email = ?
    DB-->>Auth: User data

    alt User not found
        Auth-->>API: 404 User not found
        API-->>Client: Error response
        Client-->>User: Show error
    else User found
        Auth->>Auth: Verify password hash

        alt Invalid password
            Auth-->>API: 401 Invalid credentials
            API-->>Client: Error response
            Client-->>User: Show error
        else Valid password
            Auth->>Auth: Generate JWT token
            Auth->>DB: UPDATE last_login
            Auth-->>API: 200 + JWT token
            API-->>Client: Success + token
            Client->>Client: Store token in localStorage
            Client-->>User: Redirect to dashboard
        end
    end
```

## Token Refresh Flow

```mermaid
sequenceDiagram
    participant Client
    participant API as API Gateway
    participant Auth as Auth Service
    participant Cache as Redis Cache

    Client->>API: GET /api/user/profile<br/>(with expired token)
    API->>Auth: Validate token
    Auth->>Auth: Check expiration
    Auth-->>API: 401 Token expired
    API-->>Client: Token expired

    Client->>API: POST /api/auth/refresh<br/>(with refresh token)
    API->>Auth: Validate refresh token
    Auth->>Cache: GET refresh_token
    Cache-->>Auth: Token data

    alt Refresh token valid
        Auth->>Auth: Generate new JWT
        Auth->>Cache: UPDATE token
        Auth-->>API: 200 + new JWT
        API-->>Client: New token
        Client->>API: Retry GET /api/user/profile<br/>(with new token)
        API-->>Client: 200 + profile data
    else Refresh token invalid
        Auth-->>API: 401 Refresh token invalid
        API-->>Client: Unauthorized
        Client->>Client: Clear tokens
        Client->>Client: Redirect to login
    end
```

## Two-Factor Authentication Flow

```mermaid
sequenceDiagram
    participant User
    participant Client
    participant API as API Gateway
    participant Auth as Auth Service
    participant DB as Database
    participant SMS as SMS Service

    User->>Client: Enable 2FA
    Client->>API: POST /api/auth/2fa/enable
    API->>Auth: Generate 2FA secret
    Auth->>Auth: Create QR code
    Auth->>DB: SAVE 2FA secret (encrypted)
    Auth-->>API: QR code + backup codes
    API-->>Client: Display QR code
    Client-->>User: Show QR + backup codes

    Note over User,Client: User scans QR with authenticator app

    User->>User: Enter 6-digit code from app
    User->>Client: Submit verification code
    Client->>API: POST /api/auth/2fa/verify
    API->>Auth: Validate code
    Auth->>Auth: Verify TOTP code

    alt Code valid
        Auth->>DB: UPDATE 2fa_enabled = true
        Auth-->>API: 200 2FA enabled
        API-->>Client: Success
        Client-->>User: 2FA activated
    else Code invalid
        Auth-->>API: 400 Invalid code
        API-->>Client: Error
        Client-->>User: Try again
    end
```

## Login with 2FA

```mermaid
sequenceDiagram
    participant User
    participant Client
    participant API as API Gateway
    participant Auth as Auth Service
    participant DB as Database

    User->>Client: Enter email + password
    Client->>API: POST /api/auth/login
    API->>Auth: Validate credentials
    Auth->>DB: SELECT user
    DB-->>Auth: User data (2fa_enabled = true)

    Auth->>Auth: Verify password
    Auth->>Auth: Generate session ID
    Auth-->>API: 200 + require_2fa: true
    API-->>Client: Need 2FA code

    Client-->>User: Show 2FA input
    User->>User: Open authenticator app
    User->>Client: Enter 6-digit code

    Client->>API: POST /api/auth/2fa/validate<br/>(session_id + code)
    API->>Auth: Verify TOTP code

    alt Code valid
        Auth->>Auth: Generate JWT token
        Auth->>DB: UPDATE last_login
        Auth-->>API: 200 + JWT token
        API-->>Client: Token
        Client-->>User: Redirect to dashboard
    else Code invalid
        Auth-->>API: 401 Invalid 2FA code
        API-->>Client: Error (attempts left)
        Client-->>User: Show error + retry
    end
```

## Password Reset Flow

```mermaid
sequenceDiagram
    participant User
    participant Client
    participant API as API Gateway
    participant Auth as Auth Service
    participant DB as Database
    participant Email as Email Service

    User->>Client: Click "Forgot Password"
    Client-->>User: Show email input
    User->>Client: Enter email
    Client->>API: POST /api/auth/reset-password

    API->>Auth: Request password reset
    Auth->>DB: SELECT user WHERE email = ?

    alt User exists
        DB-->>Auth: User data
        Auth->>Auth: Generate reset token (1hr expiry)
        Auth->>DB: SAVE reset token
        Auth->>Email: Send reset email
        Email-->>User: Email with reset link
        Auth-->>API: 200 Email sent
        API-->>Client: Success
        Client-->>User: Check your email
    else User not found
        Auth-->>API: 200 Email sent (same response for security)
        API-->>Client: Success
        Client-->>User: Check your email
    end

    Note over User,Email: User clicks link in email

    User->>Client: Click reset link
    Client->>API: GET /api/auth/reset/:token
    API->>Auth: Validate reset token
    Auth->>DB: SELECT token

    alt Token valid
        DB-->>Auth: Token data
        Auth-->>API: 200 Token valid
        API-->>Client: Show password form
        Client-->>User: Enter new password

        User->>Client: Submit new password
        Client->>API: POST /api/auth/reset/:token
        API->>Auth: Update password
        Auth->>Auth: Hash new password
        Auth->>DB: UPDATE password + DELETE reset token
        Auth-->>API: 200 Password updated
        API-->>Client: Success
        Client-->>User: Password changed, go to login
    else Token invalid/expired
        Auth-->>API: 400 Invalid token
        API-->>Client: Error
        Client-->>User: Token expired, request new link
    end
```

## OAuth Social Login Flow

```mermaid
sequenceDiagram
    participant User
    participant Client
    participant API as API Gateway
    participant Auth as Auth Service
    participant OAuth as OAuth Provider (Google)
    participant DB as Database

    User->>Client: Click "Sign in with Google"
    Client->>API: GET /api/auth/oauth/google
    API->>Auth: Initialize OAuth flow
    Auth->>Auth: Generate state token (CSRF protection)
    Auth-->>Client: Redirect to Google

    Client->>OAuth: Redirect with client_id + state
    OAuth-->>User: Google login page
    User->>OAuth: Enter Google credentials
    OAuth->>OAuth: Authenticate user
    OAuth-->>Client: Redirect with authorization code

    Client->>API: GET /api/auth/oauth/callback?code=xxx&state=yyy
    API->>Auth: Verify state token
    Auth->>OAuth: POST /token (exchange code for access token)
    OAuth-->>Auth: Access token + ID token

    Auth->>OAuth: GET /userinfo (with access token)
    OAuth-->>Auth: User profile data

    Auth->>DB: SELECT user WHERE oauth_id = ?

    alt User exists
        DB-->>Auth: Existing user
        Auth->>DB: UPDATE last_login
    else New user
        Auth->>DB: INSERT new user
    end

    Auth->>Auth: Generate JWT token
    Auth-->>API: 200 + JWT token
    API-->>Client: Token
    Client->>Client: Store token
    Client-->>User: Redirect to dashboard
```

## Technical Details

### Token Structure

**JWT Payload:**
```json
{
  "sub": "user_id_12345",
  "email": "user@example.com",
  "role": "user",
  "iat": 1699000000,
  "exp": 1699003600
}
```

### Security Measures

1. **Password Hashing:** bcrypt with 12 rounds
2. **JWT Expiry:** 1 hour for access token, 7 days for refresh token
3. **Rate Limiting:** 5 failed attempts → 15-minute lockout
4. **CSRF Protection:** State tokens for OAuth flows
5. **HTTPS Only:** All auth endpoints require TLS
6. **Token Rotation:** Refresh tokens invalidated after use

### Error Codes

| Code | Description |
|------|-------------|
| 400 | Bad Request - Invalid input |
| 401 | Unauthorized - Invalid credentials/token |
| 403 | Forbidden - Insufficient permissions |
| 404 | Not Found - User doesn't exist |
| 429 | Too Many Requests - Rate limit exceeded |
| 500 | Internal Server Error |

### Performance Targets

- **Login:** < 200ms (P95)
- **Token Validation:** < 50ms (P95)
- **OAuth Callback:** < 500ms (P95)
- **Password Reset Email:** < 2 seconds

---

**Version:** 2.1
**Last Updated:** November 2024
**Maintained by:** Authentication Team