Create access token

Creates a new API key with the specified name, description, expiration, and permissions.

Prerequisite: Authentication must be enabled before calling this endpoint. Call PATCH /auth/enabled with {"enabled": true} using an admin JWT first. If auth_enabled is false, the server rejects this request with 403 Forbidden and the message "API key management API requires auth_enabled=true".

Permission model

Access token permissions use a bitmask model.

Name	Value	Meaning
read	1	Read access
write	2	Write access
admin	4	Admin access

admin is an independent permission bit. It does not automatically grant read or write.

Common combinations:

Bitmask	Permission string	Meaning
1	read	Read only
2	write	Write only
4	admin	Admin only
5	read,admin	Read and admin
6	write,admin	Write and admin
7	read,write,admin	Read, write, and admin

The create-token API accepts the canonical comma-separated permission names, and the server stores them as the corresponding bitmask.

When using an admin JWT, the server uses the persisted JWT secret from server_params.btr. If ACTIAN_VECTORAI_JWT_SECRET is set at startup, that value overrides the persisted secret and is saved for subsequent restarts.

POST /auth/api_key

Create access token

cURL

curl -X POST http://localhost:6573/auth/api_key \
  -H "Content-Type: application/json" \
  -H 'Authorization: Bearer <admin-jwt-or-access-token>' \
  -d '{
    "name": "reader-admin-token",
    "description": "Used by the analytics dashboard to run read-only admin checks.",
    "will_expire": true,
    "expires_in_seconds": 86400,
    "permission": "read,admin"
  }'

200

{
  "id": 12,
  "name": "reader-admin-token",
  "description": "Used by the analytics dashboard to run read-only admin checks.",
  "api_key": "vdai_<newly-generated-token>",
  "created_at": "2026-04-02T08:30:00Z",
  "expired_at": "2026-04-03T08:30:00Z",
  "will_expire": true,
  "permission": "read,admin"
}

Authorizations

Authorization · string · header · required

Admin JWT obtained from the login endpoint.

Headers

Authorization · string · required

Admin JWT or admin access token. Format Bearer <admin-jwt-or-access-token>.

Body

application/json

name · string · required

Human-readable name for the token.

permission · string · required

Comma-separated permission names. Valid values are read, write, admin, or any combination.

Example:

"read,admin"

description · string

Optional description of the token's intended use.

will_expire · boolean · default: false

Whether the token expires. When false, the token is valid indefinitely.

expires_in_seconds · integer

Number of seconds until the token expires. Only applies when will_expire is true.

Response

200

application/json

Token created successfully.

id · integer

Unique identifier for the access token.

name · string

Human-readable name for the token.

description · string

Description of the token's intended use.

api_key · string

The raw API key value. Store this securely, as it cannot be retrieved after creation.

created_at · string<date-time>

Timestamp when the token was created, in RFC 3339 UTC format.

expired_at · string<date-time> | null

Timestamp when the token expires, in RFC 3339 UTC format. null when will_expire is false.

will_expire · boolean

Whether the token has an expiration date.

permission · string

Comma-separated permission names assigned to the token.