Authentication API

AI Admin Panel uses Keycloak OIDC as the sole authentication provider. This page covers the login flow, API key management, and session handling.

OIDC Login Flow

Browser-based authentication uses the OpenID Connect Authorization Code flow with Keycloak.

Flow Overview

Browser → Panel (/api/auth/login)
  → Redirect to Keycloak authorize endpoint
  → User enters credentials on Keycloak login page
  → Keycloak redirects back with authorization code
  → Panel exchanges code for tokens
  → Panel creates session, sets cookie
  → Redirect to dashboard

Endpoints

GET /api/auth/login

Initiates the OIDC login flow. Redirects the browser to Keycloak's authorization endpoint.

Query Parameters:

Parameter	Description
redirect	URL to redirect to after successful login (default: /)

Response: 302 Redirect to Keycloak

GET /api/auth/callback

Handles the OIDC callback from Keycloak. Exchanges the authorization code for tokens, creates a session, and redirects to the application.

This endpoint is called by Keycloak after the user authenticates — it should not be called directly.

POST /api/auth/logout

Ends the current session and logs out of Keycloak.

Request:

curl -X POST https://panel.example.com/api/auth/logout \
  -H "Cookie: session=..."

Response: 200 OK

{
  "message": "Logged out successfully"
}

GET /api/auth/me

Returns the current authenticated user's profile.

Request:

curl https://panel.example.com/api/auth/me \
  -H "Cookie: session=..."

Response: 200 OK

{
  "id": "usr_abc123",
  "email": "admin@example.com",
  "name": "Admin User",
  "role": "admin",
  "customer_id": null,
  "created_at": "2026-03-01T00:00:00Z"
}

API Keys

API keys provide programmatic access to the API without browser-based OIDC login.

Creating an API Key

POST /api/auth/api-keys

Request:

curl -X POST https://panel.example.com/api/auth/api-keys \
  -H "Cookie: session=..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD Pipeline",
    "expires_at": "2027-03-29T00:00:00Z"
  }'

Field	Required	Description
name	Yes	Descriptive name for the key
expires_at	No	Expiration timestamp (null = never expires)

Response: 201 Created

{
  "id": "key_abc123",
  "name": "CI/CD Pipeline",
  "key": "aap_k1_aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789",
  "created_at": "2026-03-29T10:00:00Z",
  "expires_at": "2027-03-29T00:00:00Z"
}

The key value is shown only once at creation time. Store it securely — it cannot be retrieved again.

Using an API Key

Include the API key in the Authorization header:

curl https://panel.example.com/api/services \
  -H "Authorization: Bearer aap_k1_aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789"

API keys inherit the permissions of the user who created them.

Listing API Keys

GET /api/auth/api-keys

Response: 200 OK

{
  "data": [
    {
      "id": "key_abc123",
      "name": "CI/CD Pipeline",
      "created_at": "2026-03-29T10:00:00Z",
      "expires_at": "2027-03-29T00:00:00Z",
      "last_used_at": "2026-03-29T14:30:00Z"
    }
  ],
  "total": 1
}

Note: The actual key value is not included in list responses.

Revoking an API Key

DELETE /api/auth/api-keys/:id

Request:

curl -X DELETE https://panel.example.com/api/auth/api-keys/key_abc123 \
  -H "Authorization: Bearer aap_k1_..."

Response: 204 No Content

Revoked keys are immediately invalid. Any requests using the revoked key will return 401 Unauthorized.

Session Management

Session Storage

Sessions are stored in Valkey with a configurable TTL (default: 24 hours). The session cookie is:

• HttpOnly — not accessible via JavaScript
• Secure — only sent over HTTPS
• SameSite=Lax — CSRF protection
• Encrypted with the SESSION_SECRET environment variable

Session Refresh

Sessions are automatically extended on each request. The TTL resets to 24 hours whenever the session is used. Sessions that are idle for 24 hours expire automatically.

Concurrent Sessions

Users can have multiple active sessions (e.g., from different browsers or devices). Logging out from one session does not affect others.

Role-Based Access

API endpoints enforce role-based access control:

Role	Access Level
admin	Full access to all endpoints and all customers' data
operator	Manage services and customers, deploy, view all data
viewer	Read-only access to assigned customer's resources

Customer-scoped users (with a customer_id) can only access resources belonging to their customer, regardless of role.