Authentication API#

The Authentication API provides endpoints for user management, login, token handling, and authentication configuration.

Overview#

All authentication endpoints are prefixed with /api/auth. When authentication is enabled, most other API endpoints require a valid JWT token in the Authorization: Bearer <token> header.

Endpoints#

GET /api/auth/status#

Returns the current authentication status.

Response#

{
  "enabled": true,
  "has_users": true,
  "setup_skipped": false
}

POST /api/auth/login#

Authenticates a user and returns JWT tokens.

Request body#

{
  "username": "admin",
  "password": "yourpassword"
}

Response#

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer"
}

Error responses#

Example#

curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "yourpassword"}'

POST /api/auth/refresh#

Exchanges a refresh token for new access and refresh tokens.

Request body#

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

Response#

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer"
}

Error responses#

POST /api/auth/verify#

Verifies that an access token is valid.

Request body#

{
  "token": "eyJhbGciOiJIUzI1NiIs..."
}

Response#

{
  "valid": true,
  "username": "admin"
}

POST /api/auth/setup#

Creates the first user account and enables authentication. Only works when no users exist.

Request body#

{
  "username": "admin",
  "password": "yourpassword"
}

Response#

{
  "message": "User created successfully",
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
}

Error responses#

POST /api/auth/skip-setup#

Skips the initial setup wizard, leaving authentication disabled.

Response#

{
  "message": "Setup skipped, authentication disabled"
}

POST /api/auth/enable#

Enables authentication. Requires at least one user to exist.

Response#

{
  "message": "Authentication enabled"
}

Error responses#

POST /api/auth/disable#

Disables authentication, allowing unauthenticated access to all endpoints.

Response#

{
  "message": "Authentication disabled"
}

User management endpoints#

These endpoints require authentication when auth is enabled.

GET /api/auth/users#

Lists all user accounts.

Response#

{
  "users": [
    {
      "username": "admin",
      "disabled": false
    },
    {
      "username": "readonly",
      "disabled": true
    }
  ]
}

POST /api/auth/users#

Creates a new user account.

Request body#

{
  "username": "newuser",
  "password": "userpassword"
}

Response#

{
  "message": "User created successfully",
  "username": "newuser"
}

Error responses#

PUT /api/auth/users/{username}#

Updates a user account (enable/disable).

Path parameters#

Request body#

{
  "disabled": true
}

Response#

{
  "message": "User updated successfully",
  "username": "readonly",
  "disabled": true
}

Error responses#

DELETE /api/auth/users/{username}#

Deletes a user account.

Path parameters#

Response#

{
  "message": "User deleted successfully"
}

Error responses#

Token structure#

JWT tokens contain the following claims:

{
  "sub": "admin",
  "exp": 1704067200,
  "type": "access"
}

Token lifetimes#

Using authentication with other endpoints#

When authentication is enabled, include the access token in the Authorization header:

curl -X GET http://localhost:8000/api/process/processes \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

WebSocket authentication#

For WebSocket connections, pass the token as a query parameter:

ws://localhost:8000/ws/status?token=eyJhbGciOiJIUzI1NiIs...

Error handling#

Common error responses#

Token refresh flow#

When receiving a 401 response:

1. Send the refresh token to POST /api/auth/refresh
2. If successful, retry the original request with the new access token
3. If refresh fails, redirect the user to login

Related pages#

• Authentication Feature Guide
• WebSocket API
• Process Management API