Auth API

The Auth API provides a single endpoint for refreshing Keycloak OIDC access tokens. It is only active when AUTH_PROVIDER=keycloak.

---

POST /auth/refresh

Exchange a Keycloak refresh token for a new access token and refresh token pair.

Use this endpoint when an access token has expired and you need to obtain a new one without requiring the user to re-authenticate.

Request body

{
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5..."
}

Field	Type	Required	Description
refresh_token	string	Yes	A valid Keycloak refresh token

Response — 200 OK

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

Field	Description
access_token	New access token. Use as Authorization: Bearer <access_token> on all subsequent requests.
refresh_token	New refresh token. Replace the old one — Keycloak may rotate it.
token_type	Always "bearer"

Error responses

Status	Condition
401	Refresh token is expired or invalid
500	Keycloak server unreachable

Example

# Refresh an expired token
RESPONSE=$(curl -s -X POST http://localhost:8080/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "eyJhbGciOiJSUzI1NiIsInR5..."}')

ACCESS_TOKEN=$(echo $RESPONSE | jq -r '.access_token')
REFRESH_TOKEN=$(echo $RESPONSE | jq -r '.refresh_token')

# Use the new access token
curl -X POST "http://localhost:8080/event/infer/my-agent" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "Hello", "user_id": "user-1", "session_id": "session-abc"}'

---

When to use this endpoint

This endpoint is only relevant when AUTH_PROVIDER=keycloak. For api_token and jwt auth providers, tokens do not expire in the same way and this endpoint is not needed.

Typical usage pattern:

1. Obtain an initial access token and refresh token from Keycloak directly (via the Keycloak login flow or client credentials grant).
2. Use the access token on all Alquimia API requests.
3. When a request returns 401, call POST /auth/refresh with the refresh token.
4. Replace both tokens with the values from the response.
5. Retry the original request with the new access token.

---

Keycloak configuration

Set these environment variables to enable Keycloak auth:

AUTH_PROVIDER=keycloak
KEYCLOAK_SERVER_URL=https://keycloak.example.com
KEYCLOAK_REALM=my-realm
KEYCLOAK_CLIENT_ID=alquimia-runtime
KEYCLOAK_CLIENT_SECRET=<client-secret>
KEYCLOAK_ADMIN_CLIENT_SECRET=<admin-client-secret>
KEYCLOAK_CALLBACK_URI=https://runtime.example.com/auth/callback

See Configuration Reference for the full list of Keycloak settings.

---

Related pages

• Configuration Reference — AUTH_PROVIDER and Keycloak settings
• Inference Endpoints — authentication requirements for all inference endpoints