API Authentication

Authentication model#

The application authenticates users through POST /api/v1/auth/login. A successful login returns an access_token, a refresh_token, an expires_at timestamp, and sets auth cookies for browser sessions. Backend auth dependencies also accept bearer credentials, but the product UI is session-based and workspace-scoped.

What the real login flow expects#

1. email_or_username and password are required.
2. totp_code is required when two-factor authentication is enabled.
3. device_name is optional but useful for session review and audit.
4. Some login attempts can return requires_totp_setup or requires_totp with a temporary token.
5. Workspace setup is handled by POST /api/v1/auth/workspace/setup and the frontend /setup page.

Example request#

curl -X POST "http://localhost:5678/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email_or_username": "admin@example.com",
    "password": "SecurePassword123!",
    "totp_code": "123456",
    "device_name": "Docs Automation Runner"
  }'

Required headers#