Auth API

Auth endpoints are only available when the server is configured with an auth section. Without auth configuration, these endpoints return 404.

Login

POST /api/auth/login

Authenticates with email and password. Returns a JWT access token and a refresh token.

Request body:

{
  "email": "admin@stroem.local",
  "password": "admin"
}

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Status	Description
401	Invalid email or password
404	Auth not configured

Refresh Token

POST /api/auth/refresh

Exchanges a refresh token for a new access/refresh token pair. The old refresh token is revoked (rotation).

Request body:

{
  "refresh_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "f1e2d3c4-b5a6-0987-dcba-0987654321fe"
}

Status	Description
401	Invalid or expired refresh token

Logout

POST /api/auth/logout

Revokes a refresh token.

Request body:

{
  "refresh_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Response:

{
  "status": "ok"
}

Get Current User

GET /api/auth/me

Returns the authenticated user’s information. Requires a valid JWT access token.

Headers:

Authorization: Bearer <access_token>

Response:

{
  "user_id": "d1e2f3a4-b5c6-7890-abcd-ef1234567890",
  "name": null,
  "email": "admin@stroem.local",
  "is_admin": true,
  "groups": ["devops", "engineering"],
  "created_at": "2025-02-11T10:00:00Z"
}

Status	Description
401	Missing or invalid access token

API Keys

Create API Key

POST /api/auth/api-keys

Creates a new API key for the authenticated user. Requires JWT authentication (not API key auth).

Request body:

{
  "name": "CI Pipeline",
  "expires_in_days": 90
}

Field	Required	Description
name	Yes	A descriptive name for the key
expires_in_days	No	Days until the key expires (null = never)

Response:

{
  "key": "strm_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "name": "CI Pipeline",
  "prefix": "strm_a1b",
  "expires_at": "2026-05-27T12:00:00+00:00"
}

The key field is only returned at creation time. Store it securely.

Status	Description
400	Empty name
401	Not authenticated

List API Keys

GET /api/auth/api-keys

Lists the authenticated user’s API keys. The raw key is never returned.

Response:

[
  {
    "prefix": "strm_a1b",
    "name": "CI Pipeline",
    "created_at": "2026-02-26T12:00:00+00:00",
    "expires_at": "2026-05-27T12:00:00+00:00",
    "last_used_at": "2026-02-26T14:30:00+00:00"
  }
]

Delete API Key

DELETE /api/auth/api-keys/{prefix}

Revokes an API key by its prefix. Only the key’s owner can delete it.

Status	Description
200	Key revoked
404	Key not found

Server Config

GET /api/config

Returns server configuration for the UI. This is a public endpoint (no auth required).

Response:

{
  "auth_required": true,
  "has_internal_auth": true,
  "oidc_providers": [
    { "id": "google", "display_name": "Google" }
  ],
  "acl_enabled": false,
  "version": "0.7.3"
}

Field	Description
auth_required	Whether authentication is enabled
has_internal_auth	Whether email/password login is available
oidc_providers	List of configured OIDC providers
acl_enabled	Whether ACL authorization rules are configured
version	Server version string

User Management (Admin Only)

The following endpoints require admin privileges. Non-admin users receive 403 Forbidden.

List Users

GET /api/users?limit=20&offset=0

Returns paginated list of all users with their admin status, groups, and auth methods.

Get User

GET /api/users/{id}

Returns detailed user information including groups.

Set Admin Status

PUT /api/users/{id}/admin

Request body:

{
  "is_admin": true
}

Admins cannot revoke their own admin status.

Status	Description
400	Attempting to revoke own admin status
403	Not an admin
404	User not found

Set User Groups

PUT /api/users/{id}/groups

Request body:

{
  "groups": ["devops", "engineering"]
}

Replaces all groups for the user. Group names must be 1-64 characters, alphanumeric with _ and -.

Status	Description
400	Invalid group name
403	Not an admin
404	User not found

List Groups

GET /api/groups

Returns all distinct group names across all users.

Response:

{
  "groups": ["devops", "engineering", "qa"]
}

OIDC Login Start

GET /api/auth/oidc/{provider}

Initiates an OIDC Authorization Code + PKCE flow. Redirects to the identity provider.

Parameter	Description
provider	OIDC provider ID from config

Response: 302 redirect to the identity provider’s authorization endpoint.

Status	Description
404	Unknown OIDC provider

OIDC Callback

GET /api/auth/oidc/{provider}/callback?code=AUTH_CODE&state=CSRF_STATE

Handles the callback from the identity provider. Validates state, exchanges the authorization code for tokens, validates the ID token, provisions the user (JIT), and issues internal JWT tokens.

On success: 302 redirect to /login/callback#access_token=AT&refresh_token=RT

On error: 302 redirect to /login/callback#error=URL_ENCODED_MSG

JIT user provisioning

1. If an auth link for this provider + external ID exists → return that user
2. If a user with the same email exists → create an auth link and return that user
3. Otherwise → create a new user (no password) + auth link