Authentication¶

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

Authentication Flow¶

sequenceDiagram
    participant Client
    participant API as Flex Video API
    Client->>API: POST /auth/login
    API-->>Client: { token, expires }
    Client->>API: Authorization: Bearer <token>
    API-->>Client: Protected resource

Check Auth Status¶

Determine if authentication is enabled:

curl -k https://<encoder-ip>: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 -k -X PUT https://<encoder-ip>:3539/flex/auth/password \
  -H "Content-Type: application/json" \
  -d '{"password": "your-secure-password"}'

Changing Password¶

Requires authentication:

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

Removing Password¶

Disables authentication:

curl -k -X DELETE https://<encoder-ip>:3539/flex/auth/password \
  -H "Authorization: Bearer <token>"

Session Tokens¶

Login¶

curl -k -X POST https://<encoder-ip>: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 -k -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  https://<encoder-ip>:3539/flex/pipeline

Logout¶

Invalidate the current token:

curl -k -X POST https://<encoder-ip>:3539/flex/auth/logout \
  -H "Authorization: Bearer <token>"

Public Endpoints¶

These endpoints never require authentication:

Protected Endpoints¶

All Other Endpoints¶

When auth is enabled, all other endpoints require a valid session token (Authorization: Bearer).

Rate Limiting¶

Login attempts are rate limited to 5 attempts per 15 minutes per IP address. After exceeding the limit, requests return 429 Too Many Requests with a Retry-After header.

{
  "message": "Too many login attempts. Please try again later.",
  "code": "RATE_LIMITED",
  "retry_after_seconds": 900
}

Error Responses¶

401 Unauthorized¶

Missing or invalid credentials:

{
  "error": "Unauthorized"
}

429 Too Many Requests¶

Login rate limit exceeded (see Rate Limiting above).

400 Bad Request¶

Invalid login attempt:

{
  "error": "Invalid password"
}

Security Best Practices¶

1. Use strong passwords - Passwords must be at least 12 characters (enforced by the API)
2. Use HTTPS - The API is served over HTTPS by default
3. Limit token lifetime - Tokens expire in 24 hours by default

Security¶

Passwords are hashed and tokens are encrypted at rest. Passwords are never stored in plain text.