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

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

Header	Description
`X-Tenant-ID`	Selects the effective tenant context for JWT requests and user-scoped API keys without a fixed tenant binding. 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.

For JWTs and API keys without a fixed tenant binding, omitting X-Tenant-ID leaves the request without a tenant context. Endpoints that require a tenant context reject such requests. Selecting a tenant requires active membership in that tenant; superusers can also select an active tenant without membership.

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; defaults to `true`. Set to `false` to create a user-scoped key without a fixed tenant binding.
`tenant_id`	Tenant ID for tenant-bound keys. Defaults to the current tenant context if omitted. With `tenant_bound: false`, omit this field or set it to `null`.
`user_id`	For tenant-bound keys: omit to use the current user as owner; explicitly send `null` to create a key without a user binding. With `tenant_bound: false`, the current user is used if no user ID is provided.
`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

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.

Requested key permissions must be allowed for key creation. For tenant-bound keys with a user binding, the intended owner’s permissions are also taken into account. Unknown permissions result in 400 Bad Request; permissions outside the allowed scope result in 403 Forbidden. The API rejects creation rather than automatically reducing the requested list.

Administrative options

Superusers can use the X-Impersonate-User-ID header to select another active user as the effective user. Requests without superuser authorization are rejected with 403 Forbidden. Tenant selection is still validated.

The API key creation body also accepts is_superuser, which defaults to false. Only superusers may set it to true, and the key must be bound to a user. Superuser access within a tenant context requires both a key marked for superuser access and an owner who is a superuser.

Security

API keys are confidential credentials. Never share them publicly or store them in public repositories.