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