Authentication¶

Flex Video supports optional password-based authentication with session tokens and API keys.

Authentication Flow¶

┌─────────────────────────────────────────────────────────────┐
│                    Authentication Flow                       │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌──────────┐    POST /auth/login     ┌──────────────────┐  │
│  │  Client  │ ──────────────────────► │   Flex Video     │  │
│  │          │ ◄────────────────────── │   API Server     │  │
│  └──────────┘    { token, expires }   └──────────────────┘  │
│       │                                        │             │
│       │  Authorization: Bearer <token>         │             │
│       │ ─────────────────────────────────────► │             │
│       │                                        │             │
│       │ ◄───────────────────────────────────── │             │
│       │         Protected resource             │             │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Check Auth Status¶

Determine if authentication is enabled:

curl http://localhost:3539/flex/auth/status

Response:

{
  "auth_enabled": true
}

When auth_enabled is false, all endpoints are accessible without credentials.

Setting a Password¶

First-Time Setup¶

When no password is set, anyone can set one:

curl -X PUT http://localhost:3539/flex/auth/password \
  -H "Content-Type: application/json" \
  -d '{"password": "your-secure-password"}'

Changing Password¶

Requires authentication:

curl -X PUT http://localhost:3539/flex/auth/password \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"password": "new-password"}'

Removing Password¶

Disables authentication:

curl -X DELETE http://localhost:3539/flex/auth/password \
  -H "Authorization: Bearer <token>"

Session Tokens¶

Login¶

curl -X POST http://localhost:3539/flex/auth/login \
  -H "Content-Type: application/json" \
  -d '{"password": "your-password"}'

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_at": "2026-01-28T10:30:00Z"
}

Tokens are valid for 24 hours.

Using Tokens¶

Include the token in the Authorization header:

curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  http://localhost:3539/flex/pipeline

Logout¶

Invalidate the current token:

curl -X POST http://localhost:3539/flex/auth/logout \
  -H "Authorization: Bearer <token>"

API Keys¶

API keys provide service-to-service authentication without login.

Configuration¶

The API key is set via environment variable:

# .env
FLEX_API_KEY=your-secure-api-key

The installer auto-generates a unique key during installation.

Using API Keys¶

Include the key in the X-API-Key header:

curl -H "X-API-Key: your-secure-api-key" \
  http://localhost:3539/flex/pipeline

Use Cases¶

Public Endpoints¶

These endpoints never require authentication:

Protected Endpoints¶

Trigger Endpoints¶

MediaMTX webhook endpoints require API key authentication:

/flex/triggers/*

The MediaMTX container is configured with the same FLEX_API_KEY to authenticate webhook calls.

All Other Endpoints¶

When auth is enabled, all other endpoints require either:

• Valid session token (Authorization: Bearer)
• Valid API key (X-API-Key)

Error Responses¶

401 Unauthorized¶

Missing or invalid credentials:

{
  "error": "Unauthorized"
}

400 Bad Request¶

Invalid login attempt:

{
  "error": "Invalid password"
}

Security Best Practices¶

1. Use strong passwords - Minimum 12 characters, mixed case, numbers, symbols
2. Rotate API keys - Periodically regenerate keys
3. Use HTTPS - In production, terminate TLS at a reverse proxy
4. Limit token lifetime - Tokens expire in 24 hours by default
5. Secure .env file - Restrict file permissions (chmod 600)

Implementation Notes¶

Token Storage¶

Tokens are stored in an encrypted Hive database. Token validation checks:

1. Token exists in store
2. Token hasn't expired
3. Token hasn't been invalidated (logout)

Password Hashing¶

Passwords are hashed using bcrypt before storage. The original password is never stored.

API Key Validation¶

API keys are compared using constant-time comparison to prevent timing attacks.