---
title: "Mint a personal access token"
method: POST
path: "/api/api_keys"
tags: ["api keys"]
---

# Mint a personal access token

`POST /api/api_keys`

## Request

- Base URL: `https://telawiki.com`
- URL: `https://telawiki.com/api/api_keys`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `tela_session`

The raw token is returned **once**, in `api_key.key`, and is stored only as an HMAC — it cannot be recovered. In bearer mode this route needs `admin` scope; a session works for any user. Only instance admins may mint `admin`-scoped tokens.

## Request body

- object
  - `name` string, required: Label, for your own bookkeeping.
  - `scope` 'read' | 'write' | 'admin', required: `read` permits GET and HEAD; `write` and `admin` permit any method.
  - `space_id` integer, nullable: Pin the token to one space. Omit for instance-wide access.
  - `expires_at` string, nullable: `YYYY-MM-DD HH:MM:SS` UTC, must be in the future. Omit for a token that never expires.

## Response `201`

Created. `api_key.key` is the raw token — store it now.

- object
  - `api_key` APIKeyWithSecret, required
    - `id` integer, required
    - `name` string, required
    - `key_prefix` string, required: The first 8 characters after `tela_pat_`, for identifying a token you still hold.
    - `scope` 'read' | 'write' | 'admin', required: `read` permits GET and HEAD; `write` and `admin` permit any method.
    - `space_id` integer, nullable, required: Non-null when the token is pinned to one space.
    - `last_used_at` string, nullable
    - `expires_at` string, nullable
    - `created_at` string, required: `YYYY-MM-DD HH:MM:SS` in UTC.
    - `revoked_at` string, nullable
    - `key` string, required: The raw token, returned **once** and never recoverable — only its HMAC is stored.

## Other responses

- `400`: Malformed request. `code` is usually `bad_request` or `invalid_json`.
- `401`: `unauthorized` — no valid credential. A malformed bearer token never falls back to the session cookie.
- `403`: `api_key_scope` (bearer without `admin`) or `forbidden` (only instance admins may mint `admin` tokens).
- `500`: `internal` — server error.

---

[API](https://skmtc.dev/telawiki/apis/tela-rest-api.md) · [All operations](https://skmtc.dev/telawiki/apis/tela-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/telawiki/apis/tela-rest-api/revisions/f316f31f6fcb?raw)