Authentication
Protected LIVOI API endpoints require a valid bearer token in the Authorization header:
Authorization: Bearer <TOKEN>The bearer value can contain two types of credentials:
- a JWT, when the token consists of three dot-separated segments
- a LIVOI API key, when the token is not a JWT
API keys do not use a separate header. Always send them as:
Authorization: Bearer <API_KEY>The request is rejected if the header is missing or its format is invalid.
API key format
Section titled “API key format”Internally, API keys use this format:
<kind>_<instance>_<key_id>_<marker>.<secret>These components are provided for reference only:
| Field | Values |
|---|---|
kind | pk, sk, wk |
instance | prod, staging, dev, test, local |
Clients should treat API keys as opaque secrets and should not parse their format.
Additional headers
Section titled “Additional headers”| Header | Description |
|---|---|
X-Tenant-ID | Selects the effective tenant context for JWT requests. For tenant-bound API keys, the value must match the key’s tenant binding or be omitted. |
X-Request-ID | Optional client request identifier. If missing or invalid, the backend generates a request ID. |
API key management
Section titled “API key management”Manage API keys through the LIVOI dashboard. The API also provides these endpoints:
| Method | Path | Purpose |
|---|---|---|
GET | /api/v1/auth/me | Get the current authentication context |
POST | /api/v1/auth/api-keys/ | Create an API key |
GET | /api/v1/auth/api-keys/ | List API keys |
DELETE | /api/v1/auth/api-keys/{api_key_id} | Delete an API key |
POST | /api/v1/auth/api-keys/{api_key_id}/revoke | Revoke an API key |
Relevant request body fields when creating an API key include:
| Field | Description |
|---|---|
name | Display name of the key |
description | Optional description |
kind | Key type, e.g. pk, sk or wk |
instance | Target instance, e.g. prod, staging, dev, test or local |
tenant_bound | Binds the key to a tenant context |
tenant_id | Tenant ID for tenant-bound keys |
user_id | User binding if the key is created for a specific user |
expires_at | Optional expiration date |
permissions | Permissions to grant to the key |
The plaintext api_key field is returned only when the key is created. The full secret cannot be retrieved again afterward.
Permissions
Section titled “Permissions”The API checks specific permissions rather than simply requiring a general administrator role. API key management uses permissions including api_keys.create, api_keys.create.own, and api_keys.create.any.
New key permissions are limited to the effective permissions of the requesting context. A user or key cannot grant permissions beyond those allowed by its own context.
Security
Section titled “Security”API keys are confidential credentials. Never share them publicly or store them in public repositories.