Authentication & Users

Overview

The EdgeFlow SaaS platform provides a complete authentication system with JWT tokens, optional multi-factor authentication (TOTP), session management via Redis, and API key authentication for programmatic access. All passwords are hashed with bcrypt and all tokens are signed with HMAC-SHA256.

Registration

Create a new account along with an initial organization:

POST /api/v1/auth/register

{
  "email": "user@example.com",
  "password": "SecurePass123",
  "first_name": "Alice",
  "last_name": "Smith",
  "organization_name": "My Company",
  "organization_slug": "my-company",
  "accept_terms": true,
  "subscribe_newsletter": false
}

# Response (201 Created)
{
  "user": {
    "id": "usr_abc123",
    "email": "user@example.com",
    "first_name": "Alice",
    "last_name": "Smith",
    "email_verified": false
  },
  "organization": {
    "id": "org_xyz789",
    "name": "My Company",
    "slug": "my-company",
    "plan": "free"
  }
}

Login

Authenticate with email and password to receive JWT tokens:

POST /api/v1/auth/login

{
  "email": "user@example.com",
  "password": "SecurePass123",
  "organization_id": "org_xyz789"
}

# Response (200 OK)
{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "session_id": "ses_abc123",
  "user": {
    "id": "usr_abc123",
    "email": "user@example.com",
    "first_name": "Alice",
    "last_name": "Smith",
    "organization_id": "org_xyz789",
    "role": "owner"
  }
}

MFA Login

If MFA is enabled, the first login returns a challenge. Submit the TOTP code to complete authentication:

# Step 1: Login returns MFA challenge
POST /api/v1/auth/login
{"email": "user@example.com", "password": "SecurePass123"}

{
  "requires_mfa": true,
  "message": "MFA code required"
}

# Step 2: Submit MFA code
POST /api/v1/auth/login
{
  "email": "user@example.com",
  "password": "SecurePass123",
  "mfa_code": "482901"
}

# Response: Full login response with tokens

JWT Tokens

EdgeFlow uses two types of JWT tokens signed with HMAC-SHA256:

Access Token Claims

{
  "user_id": "usr_abc123",
  "email": "user@example.com",
  "organization_id": "org_xyz789",
  "role": "owner",
  "token_type": "access",
  "iss": "edgeflow-saas",
  "exp": 1708517700,
  "iat": 1708516800
}

Token Refresh

POST /api/v1/auth/refresh

{
  "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
}

# Response
{
  "access_token": "eyJhbGciOiJIUzI1NiIs..."
}

Multi-Factor Authentication

EdgeFlow supports TOTP-based MFA compatible with apps like Google Authenticator, Authy, and 1Password. When enabled, users must provide a 6-digit code on every login.

Setup Flow

1. Generate a TOTP secret and QR code URL
2. User scans the QR code with their authenticator app
3. User verifies by entering a valid 6-digit code
4. 8 backup recovery codes are generated (format: XXXX-XXXX)

Backup Codes

During MFA setup, 8 single-use backup codes are generated. Each code follows the XXXX-XXXX format using alphanumeric characters. Backup codes are hashed before storage and can be used if the authenticator app is unavailable.

Session Management

Sessions are stored in Redis with a default duration of 24 hours. Each session tracks the user's IP address, user agent, and access timestamps.

API Key Authentication

For programmatic access and service-to-service communication, EdgeFlow provides API keys as an alternative to JWT tokens.

API keys are sent via the X-API-Key header. Keys are stored as SHA256 hashes and support optional expiration dates and permission scopes.

# Using an API key
curl -H "X-API-Key: edgeflow_abcdef..." \
  https://saas.edgx.cloud/api/v1/devices

User Profile

The user model includes profile information and preferences:

Profile Endpoints

# Get profile
GET /api/v1/auth/profile
Authorization: Bearer <access_token>

# Update profile
PUT /api/v1/auth/profile
Authorization: Bearer <access_token>
{
  "first_name": "Alice",
  "last_name": "Johnson",
  "locale": "en",
  "timezone": "America/New_York"
}

# Change password
POST /api/v1/auth/change-password
Authorization: Bearer <access_token>
{
  "old_password": "OldPass123",
  "new_password": "NewSecurePass456"
}

Password Policy

• Minimum length: 8 characters
• Maximum length: 72 characters (bcrypt limit)
• Hashing algorithm: bcrypt with cost factor 12
• Password reset tokens: 32-byte cryptographically random

Security Summary