---
title: "Create access token"
method: POST
path: "/auth/api_key"
tags: ["Access Tokens"]
---

# Create access token

`POST /auth/api_key`

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.

## Headers

- `Authorization` string, required

## Request body

- object
  - `name` string, required — Human-readable name for the token.
  - `description` string — Optional description of the token's intended use.
  - `will_expire` boolean — 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`.
  - `permission` string, required — Comma-separated permission names. Valid values are `read`, `write`, `admin`, or any combination.

## Response `200`

Token created successfully.

- object
  - `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, nullable — 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.

## Other responses

- `403` — Authentication is not enabled on the server.

## Changes

- **2026-06-27** `1be75c43c359` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/actiancorp/apis/actian-vectorai-db-authentication-api/changes/auth/api_key/post.md)

---

[API](https://skmtc.dev/actiancorp/apis/actian-vectorai-db-authentication-api.md) · [All operations](https://skmtc.dev/actiancorp/apis/actian-vectorai-db-authentication-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/actiancorp/actian-vectorai-db-authentication-api/revisions/1be75c43c359/schema)