Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

API key

An API key lets a machine act without a user token. A key belongs to an actor: whatever it does, it does with that actor's permissions, and every request it makes is attributable.

The secret is shown once, in the answer to its creation, and is never retrievable afterwards — only its hash is stored. Keys expire; a key without an explicit lifetime lasts 90 days, and no key may be issued for longer than a year.

List API keys

get

Returns the tenant's API keys — their labels, actors and lifetimes, never their secrets.

Filterable — id, label, ident, actorId, creatorId, expiresAt, revokedAt, usedAt, createdAt.

Sortable — id, label, ident, expiresAt, revokedAt, usedAt, createdAt.

Searchable — nothing yet.

usedAt is when the key was last accepted and revokedAt when it was withdrawn — keys that are still usable are {"field":"revokedAt","op":"isNull"}.

Authorizations
AuthorizationstringRequired

Token issued by the central equipme authentication, sent as Bearer <token>.

Query parameters
filterstringOptional

JSON filter expression

searchstringOptional

Free-text term — no effect here

sortstringOptional

Comma-separated field:direction terms

fieldsstringOptional

Selection of fields and relations

Example: label,expiresAt,usedAt
offsetintegerOptional

Number of entries to skip

Default: 0
limitintegerOptional

Page size, 1 to 100

Default: 100
Responses
200

OK

application/json
countintegerOptional
get/v1/keys
GET /api/v1/keys HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "count": 1,
  "data": [
    {
      "actor": {
        "contacts": [
          {
            "assignmentContext": "text",
            "autoAssign": true,
            "createdAt": "2026-01-01T00:00:00.000Z",
            "description": "text",
            "email": "ada.lovelace@example.com",
            "firstName": "Ada",
            "id": 17,
            "kind": "",
            "lastName": "Lovelace",
            "mobile": "text",
            "phone": "text",
            "tenant": {
              "id": 1,
              "name": "text"
            },
            "tenantId": 1,
            "title": "text",
            "updatedAt": "2026-01-01T00:00:00.000Z"
          }
        ],
        "id": 1,
        "realm": "text",
        "sub": "text",
        "tenant": {
          "id": 1,
          "name": "text"
        },
        "tenantId": 1,
        "tenantRole": "",
        "username": "text"
      },
      "actorId": 1,
      "createdAt": "text",
      "creator": {
        "contacts": [
          {
            "assignmentContext": "text",
            "autoAssign": true,
            "createdAt": "2026-01-01T00:00:00.000Z",
            "description": "text",
            "email": "ada.lovelace@example.com",
            "firstName": "Ada",
            "id": 17,
            "kind": "",
            "lastName": "Lovelace",
            "mobile": "text",
            "phone": "text",
            "tenant": {
              "id": 1,
              "name": "text"
            },
            "tenantId": 1,
            "title": "text",
            "updatedAt": "2026-01-01T00:00:00.000Z"
          }
        ],
        "id": 1,
        "realm": "text",
        "sub": "text",
        "tenant": {
          "id": 1,
          "name": "text"
        },
        "tenantId": 1,
        "tenantRole": "",
        "username": "text"
      },
      "creatorId": 1,
      "expiresAt": "text",
      "id": 1,
      "ident": "text",
      "label": "text",
      "revokedAt": "text",
      "scopes": [
        ""
      ],
      "usedAt": "text"
    }
  ]
}

Issue an API key

post

Issues an API key for an actor. label says what it is for, actorId whose permissions it carries, and ttl how long it lives — the default is 90 days and anything beyond a year is answered with 400.

The answer contains secret, and this is the only time it is shown. Store it before closing the response; a lost secret cannot be recovered, only replaced by a new key.

Authorizations
AuthorizationstringRequired

Token issued by the central equipme authentication, sent as Bearer <token>.

Body
objectOptional
or
Responses
201

Created

application/json
secretstringOptional
post/v1/keys
POST /api/v1/keys HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 2

{}
{
  "data": {
    "actor": {
      "contacts": [
        {
          "assignmentContext": "text",
          "autoAssign": true,
          "createdAt": "2026-01-01T00:00:00.000Z",
          "description": "text",
          "email": "ada.lovelace@example.com",
          "firstName": "Ada",
          "id": 17,
          "kind": "",
          "lastName": "Lovelace",
          "mobile": "text",
          "phone": "text",
          "tenant": {
            "id": 1,
            "name": "text"
          },
          "tenantId": 1,
          "title": "text",
          "updatedAt": "2026-01-01T00:00:00.000Z"
        }
      ],
      "id": 1,
      "realm": "text",
      "sub": "text",
      "tenant": {
        "id": 1,
        "name": "text"
      },
      "tenantId": 1,
      "tenantRole": "",
      "username": "text"
    },
    "actorId": 1,
    "createdAt": "text",
    "creator": {
      "contacts": [
        {
          "assignmentContext": "text",
          "autoAssign": true,
          "createdAt": "2026-01-01T00:00:00.000Z",
          "description": "text",
          "email": "ada.lovelace@example.com",
          "firstName": "Ada",
          "id": 17,
          "kind": "",
          "lastName": "Lovelace",
          "mobile": "text",
          "phone": "text",
          "tenant": {
            "id": 1,
            "name": "text"
          },
          "tenantId": 1,
          "title": "text",
          "updatedAt": "2026-01-01T00:00:00.000Z"
        }
      ],
      "id": 1,
      "realm": "text",
      "sub": "text",
      "tenant": {
        "id": 1,
        "name": "text"
      },
      "tenantId": 1,
      "tenantRole": "",
      "username": "text"
    },
    "creatorId": 1,
    "expiresAt": "text",
    "id": 1,
    "ident": "text",
    "label": "text",
    "revokedAt": "text",
    "scopes": [
      ""
    ],
    "usedAt": "text"
  },
  "secret": "text"
}

Last updated

Was this helpful?