Keys API: Manage Authentication Keys and Permissions

The keys API manages the API keys that authenticate every request to linq. A key is the only principal linq issues — there are no user accounts or session tokens. Each key carries a set of claims that determine what it can do: read-only keys (viewer), read-write keys (editor), and full-control keys (admin). All key management operations — creating, updating, or revoking keys — require a key that has the create:Key, update:Key, or delete:Key claim respectively, which only the admin preset holds by default. Authenticate all requests by passing your key in the x-api-key request header.

The raw key secret is returned only once, in the 201 Created response when a key is first created. It is never retrievable again. If a key secret is lost, the key must be revoked and a new one created.

Presets and Claims

Keys can be assigned one of three built-in presets, or given a fully custom claim list for fine-grained control.

viewer

Read access to all resources: links, rules, QR codes, domains, keys, analytics, and visits.

editor

All viewer permissions plus: create/update links and rules, create/update/delete QR codes.

admin

All editor permissions plus: archive/restore/purge links, manage domains, and manage keys.

When creating or updating a key, supply exactly one of:

preset — one of viewer, editor, or admin. The server expands it to the full claims list.
claims — an explicit array of { action, subject } objects for custom permissions.

Available actions and subjects for custom claims

Actions: read, create, update, archive, restore, purge, deleteSubjects: Link, Rule, QrCode, Domain, Key, Analytics, VisitExample custom claim: { "action": "read", "subject": "Analytics" }. Each action:subject pair must be unique within the claims array.

Endpoints

List Keys

GET /api/v1/keys

Create Key

POST /api/v1/keys

Get Key

GET /api/v1/keys/{id}

Update Key

PATCH /api/v1/keys/{id}

Revoke Key

DELETE /api/v1/keys/{id}

Get Own Key

GET /api/v1/me

List Keys

Returns a paginated list of all API keys. The raw key secret is never included. The response includes full metadata for callers with the create:Key claim (admin); other callers receive a summary (id, name, claims, preset only).

GET /api/v1/keys

Query Parameters

limit

integer

default:"50"

Maximum number of results per page. Must be between 1 and 200.

offset

integer

default:"0"

Zero-based offset for pagination.

curl https://your-linq-host/api/v1/keys \
  -H "x-api-key: lq_your_admin_key_here"

{
  "data": [
    {
      "id": "018f2c3e-aaaa-7000-8000-000000000001",
      "name": "CI Deploy Key",
      "claims": [
        { "action": "read",   "subject": "Link" },
        { "action": "create", "subject": "Link" },
        { "action": "update", "subject": "Link" }
      ],
      "preset": null,
      "prefix": "lq_ci_",
      "expires_at": "2025-01-01T00:00:00.000Z",
      "created_at": "2024-06-01T09:00:00.000Z",
      "updated_at": "2024-06-01T09:00:00.000Z"
    }
  ],
  "total": 4,
  "limit": 50,
  "offset": 0
}

Create Key

Creates a new API key. Returns the full key object including the raw secret — this value is shown exactly once and cannot be retrieved later.

POST /api/v1/keys

Requires the create:Key claim (admin preset).

Body Parameters

name

string

required

A human-readable name for the key (1–100 characters, trimmed).

preset

string

Assign a built-in permission level: viewer, editor, or admin. Provide exactly one of preset or claims.

claims

array

An explicit array of permission claims. Each entry must be { "action": string, "subject": string }. Provide exactly one of preset or claims.

expires_at

string (ISO 8601 datetime) | null

Optional expiry timestamp. The key will be rejected after this instant. Pass null or omit for a non-expiring key.

With preset
With custom claims
Response (201)

curl -X POST https://your-linq-host/api/v1/keys \
  -H "x-api-key: lq_your_admin_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Dashboard Read-Only",
    "preset": "viewer"
  }'

curl -X POST https://your-linq-host/api/v1/keys \
  -H "x-api-key: lq_your_admin_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Analytics Reporter",
    "claims": [
      { "action": "read", "subject": "Analytics" },
      { "action": "read", "subject": "Visit" }
    ],
    "expires_at": "2025-12-31T23:59:59Z"
  }'

{
  "id": "018f2c3e-bbbb-7000-8000-000000000002",
  "name": "Dashboard Read-Only",
  "claims": [
    { "action": "read", "subject": "Link" },
    { "action": "read", "subject": "Rule" },
    { "action": "read", "subject": "QrCode" },
    { "action": "read", "subject": "Domain" },
    { "action": "read", "subject": "Key" },
    { "action": "read", "subject": "Analytics" },
    { "action": "read", "subject": "Visit" }
  ],
  "preset": "viewer",
  "prefix": "lq_das_",
  "expires_at": null,
  "created_at": "2024-06-01T12:00:00.000Z",
  "updated_at": "2024-06-01T12:00:00.000Z",
  "secret": "lq_das_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

Store the secret value from the 201 response immediately and securely. It is never returned again by any endpoint. If the secret is lost, revoke the key with DELETE /api/v1/keys/{id} and create a replacement.

Get Key

Returns the metadata for a single API key by its ID. The raw secret is never included.

GET /api/v1/keys/{id}

Requires the read:Key claim.

Path Parameters

string (UUID)

required

The UUID of the key to retrieve.

curl https://your-linq-host/api/v1/keys/018f2c3e-bbbb-7000-8000-000000000002 \
  -H "x-api-key: lq_your_admin_key_here"

Update Key

Updates the name, permission preset/claims, or expiry of an existing key. All fields are optional. Provide at most one of preset or claims.

PATCH /api/v1/keys/{id}

Requires the update:Key claim (admin preset). A key cannot modify its own claims or preset — attempting to do so returns a 403 Forbidden. The name and expiry can still be updated on the caller’s own key.

Path Parameters

string (UUID)

required

The UUID of the key to update.

Body Parameters

name

string

Updated display name (1–100 characters).

preset

string

Replace the key’s permissions with a built-in preset: viewer, editor, or admin. Cannot be combined with claims.

claims

array

Replace the key’s permissions with an explicit claims list. Cannot be combined with preset.

expires_at

string (ISO 8601 datetime) | null

New expiry time, or null to remove the expiry.

curl -X PATCH https://your-linq-host/api/v1/keys/018f2c3e-bbbb-7000-8000-000000000002 \
  -H "x-api-key: lq_your_admin_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "preset": "editor", "expires_at": "2026-01-01T00:00:00Z" }'

Revoke Key

Permanently deletes an API key. Any requests using the revoked key will immediately start receiving 401 Unauthorized. This operation is irreversible. A key cannot revoke itself.

DELETE /api/v1/keys/{id}

Requires the delete:Key claim (admin preset). Returns 204 No Content on success.

Path Parameters

string (UUID)

required

The UUID of the key to revoke.

curl -X DELETE https://your-linq-host/api/v1/keys/018f2c3e-bbbb-7000-8000-000000000002 \
  -H "x-api-key: lq_your_admin_key_here"

GET /api/v1/me

Returns the full metadata for the currently authenticated key — the one whose secret is in the x-api-key header. Useful for confirming that authentication is working and for inspecting the calling key’s own claims and preset.

GET /api/v1/me

curl https://your-linq-host/api/v1/me \
  -H "x-api-key: lq_your_key_here"

{
  "id": "018f2c3e-aaaa-7000-8000-000000000001",
  "name": "CI Deploy Key",
  "claims": [
    { "action": "read",   "subject": "Link" },
    { "action": "create", "subject": "Link" },
    { "action": "update", "subject": "Link" }
  ],
  "preset": null,
  "prefix": "lq_ci_",
  "expires_at": null,
  "created_at": "2024-06-01T09:00:00.000Z",
  "updated_at": "2024-06-01T09:00:00.000Z"
}

Key Object Fields

string

UUID (v7) uniquely identifying this key.

name

string

Human-readable display name for the key.

claims

Claim[]

The full expanded list of permission claims this key holds. Each claim is { action: string, subject: string }.

preset

string | null

The preset name (viewer, editor, or admin) if the key’s claims exactly match a preset’s expansion. null for custom claim sets.

prefix

string

A short, non-secret prefix derived from the key name, included in the raw secret for human identification (e.g. lq_ci_). Never sensitive on its own.

expires_at

string (ISO 8601) | null

When the key expires and stops authenticating. null for non-expiring keys.

created_at

string (ISO 8601)

Timestamp when the key was created.

updated_at

string (ISO 8601)

Timestamp of the last metadata update.

secret

string

Only present in the POST /api/v1/keys 201 response. The full raw key value to use in x-api-key headers. Never returned by any other endpoint.

Bootstrap guard: if all keys are revoked and the key table is empty, the next server restart automatically mints a new admin key and prints its secret to the server’s standard output. This prevents a linq instance from becoming permanently inaccessible. You can also run bun run key:create --name <name> --preset <preset> [--expires <ISO date>] directly on the server to create a key without a restart.

Overview

Resources

Keys API: Manage Authentication Keys and Permissions

Presets and Claims

viewer

editor

admin

Endpoints

List Keys

Create Key

Get Key

Update Key

Revoke Key

Get Own Key

List Keys

Query Parameters

Create Key

Body Parameters

Get Key

Path Parameters

Update Key

Path Parameters

Body Parameters

Revoke Key

Path Parameters

GET /api/v1/me

Key Object Fields

Build docs developers (and LLMs) love

Overview

Resources

Documentation Index

​Presets and Claims

viewer

editor

admin

​Endpoints

List Keys

Create Key

Get Key

Update Key

Revoke Key

Get Own Key

​List Keys

​Query Parameters

​Create Key

​Body Parameters

​Get Key

​Path Parameters

​Update Key

​Path Parameters

​Body Parameters

​Revoke Key

​Path Parameters

​GET /api/v1/me

​Key Object Fields

Build docs developers (and LLMs) love

Presets and Claims

Endpoints

List Keys

Query Parameters

Create Key

Body Parameters

Get Key

Path Parameters

Update Key

Path Parameters

Body Parameters

Revoke Key

Path Parameters

GET /api/v1/me

Key Object Fields