Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.linkutm.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

API keys let server-side integrations authenticate against the linkutm API without a user JWT. Endpoints live under /api/v1/api-keys. A key:
  • Is workspace-scoped. It is created against one workspace and only ever acts within that workspace.
  • Has the format lk_live_<48 hex characters>, for example lk_live_3f1c.... The hex portion is 24 random bytes.
  • Authenticates the Links API. Pass it on Links requests instead of a user JWT.
The full key value is returned only in the create response. Store it securely at that point. The list endpoint returns the stored key records, so treat any place a key appears as sensitive.

​
Management endpoints require a JWT

The three endpoints below - create, list, and revoke - manage keys and are themselves protected by a JWT bearer token, not by an API key. The API key is what you then use to call the Links API. You also pass the x-workspace-id header so the server knows which workspace the keys belong to. 
Authorization: Bearer <jwt>
x-workspace-id: <uuid_or_slug>

​
Create an API key

POST /api/v1/api-keys
Generates a new lk_live_ key for the workspace in x-workspace-id. The key is owned by the authenticated user and scoped to that workspace.

​
Headers

HeaderRequiredNotes
Authorization: Bearer <jwt>Yes
x-workspace-id: <uuid_or_slug>YesTarget workspace, by UUID or slug
Content-Type: application/jsonYes

​
Body

​
name
string
required
A label for the key, so you can identify it later (for example production-server or zapier).
​
expiresAt
string
ISO 8601 date or datetime. After this moment the key stops validating. Omit it for a key that does not expire.

​
Example request

curl -X POST https://api.linkutm.com/api/v1/api-keys \
  -H "Authorization: Bearer $TOKEN" \
  -H "x-workspace-id: client-globex" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-server",
    "expiresAt": "2027-01-01T00:00:00.000Z"
  }'

​
Example response

{
  "id": "7c8d9e0f-1a2b-4c3d-8e5f-6a7b8c9d0e1f",
  "name": "production-server",
  "key": "lk_live_3f1c2a4b5e6d7c8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e",
  "expiresAt": "2027-01-01T00:00:00.000Z",
  "lastUsedAt": null,
  "workspaceId": "8a7b6c5d-4e3f-4a2b-9c1d-0e1f2a3b4c5d",
  "userId": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "createdAt": "2026-05-22T14:00:00.000Z"
}
The key field holds the value you use to authenticate the Links API. This is the only response that returns it as part of a fresh generation, so capture it now.

​
List API keys

GET /api/v1/api-keys
Returns all API keys for the workspace in x-workspace-id, ordered newest first.

​
Headers

HeaderRequiredNotes
Authorization: Bearer <jwt>Yes
x-workspace-id: <uuid_or_slug>YesTarget workspace, by UUID or slug

​
Example request

curl https://api.linkutm.com/api/v1/api-keys \
  -H "Authorization: Bearer $TOKEN" \
  -H "x-workspace-id: client-globex"

​
Example response

[
  {
    "id": "7c8d9e0f-1a2b-4c3d-8e5f-6a7b8c9d0e1f",
    "name": "production-server",
    "key": "lk_live_3f1c2a4b5e6d7c8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e",
    "expiresAt": "2027-01-01T00:00:00.000Z",
    "lastUsedAt": "2026-05-22T13:55:00.000Z",
    "workspaceId": "8a7b6c5d-4e3f-4a2b-9c1d-0e1f2a3b4c5d",
    "userId": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "createdAt": "2026-05-22T14:00:00.000Z"
  }
]
lastUsedAt is updated each time the key successfully authenticates a request. It is null until the key is first used.

​
Revoke an API key

DELETE /api/v1/api-keys/:id
Deletes the API key with the given ID. The key must belong to the workspace in x-workspace-id. Once deleted, the key no longer authenticates any request.

​
Headers

HeaderRequiredNotes
Authorization: Bearer <jwt>Yes
x-workspace-id: <uuid_or_slug>YesTarget workspace, by UUID or slug

​
Example request

curl -X DELETE https://api.linkutm.com/api/v1/api-keys/7c8d9e0f-1a2b-4c3d-8e5f-6a7b8c9d0e1f \
  -H "Authorization: Bearer $TOKEN" \
  -H "x-workspace-id: client-globex"

​
Example response

Returns the deleted API key record.
Revocation is immediate and permanent. Any integration still using the key starts failing right away.

​
Key expiration

A key with expiresAt set in the past is treated as invalid and fails authentication, even though the record still exists. Revoke keys you no longer need rather than relying on expiry alone.

​
API key endpoint scope

An API key covers only the Links module. The table below is the authoritative list of what the key can and cannot reach.
EndpointAPI key supported
GET /linksYes
GET /links/statsYes
GET /links/idsYes
GET /links/:idYes
POST /linksYes
PATCH /links/:idYes
DELETE /links/:idYes
POST /links/bulk-deleteYes
POST /links/bulk-archiveYes
POST /links/bulk-moveYes
POST /links/bulk-tagYes
POST /links/bulk-createYes
POST /links/check-shortcodesYes
POST /links/import/*Yes
GET /links/:id/analyticsNo — returns 401
GET /links/:id/tagsNo — route not registered
GET /links/:id/pixelsNo — returns 401
GET /analyticsNo — returns 401
GET /templatesNo — returns 401
GET /foldersNo — returns 401
GET /tagsNo — returns 401
GET /utm-rulesNo — returns 401
POST /pixelsNo — returns 401
All other modulesNo — returns 401

​
Errors

CodeWhen
400Missing name, or expiresAt is not a valid ISO 8601 date string
401Missing or invalid JWT
404API key not found, or it does not belong to the workspace in x-workspace-id
429Rate limit exceeded (100 requests/minute per IP)
See Errors for the full error envelope.