API keys
Create, revoke, and grant per-mailbox access to a key.
Every endpoint needs Authorization: Bearer lk_live_.... See
Conventions for headers, status codes
and error shape.
List API keys
GET /v1/api-keys · scope tenant:admin
Returns all API keys (active and revoked) belonging to the calling
tenant. The secret is never returned, only prefix + metadata.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
sort |
query | string (label, created_at, last_used_at, expires_at) |
Field to order by. This list holds tens of rows per account, so every column is offered and none needs an index. |
order |
query | string (asc, desc) |
Defaults to desc for the default field and asc for any other. Always tie-broken on id, so the order is total. |
Response 200
Key list
| Field | Type | Notes |
|---|---|---|
data |
array of APIKey | Required. |
Errors: 401, 403
Create an API key
POST /v1/api-keys · scope tenant:admin
Provisions a fresh API key for the calling tenant.
The full secret is included in this response ONLY, store it
immediately. The cleartext secret is not recoverable from the
argon2id hash kept server-side; rotate by creating a new key and
revoking the old one.
Request body
| Field | Type | Notes |
|---|---|---|
label |
string | Required. Free-text identifier shown in the dashboard. |
scopes |
array of string | Required. Allowed scopes on this key. |
test |
boolean | Issue a test key (lk_test_ prefix). A test key accepts sends, records them and fires a simulated delivery webhook without sending mail, and counts against no limit or allowance. |
expires_at |
string | Optional. When the key stops authenticating. Omit it for a key that does not expire. Must be in the future: an expiry already past would mint a key that fails its first request. |
Response 201
Key created, secret is in the response and shown only here.
Errors: 400, 401, 403
Update an API key
PATCH /v1/api-keys/{id} · scope tenant:admin
Changes a key’s label, scopes or expiry in place, without reissuing the secret.
Every field is optional and absent means unchanged. Renaming a key
does not clear its expiry. For expires_at there are three distinct
requests: omit the field to leave the expiry alone, send a timestamp to
set one, and send an explicit null to remove one.
Scopes are replaced wholesale, not merged. This endpoint does not
restrict which scopes you may grant, because POST /v1/api-keys never
has either: a key with tenant:admin can already mint a key with any
scope, so tenant:admin is root-equivalent for key management.
A revoked key cannot be updated.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id |
path | string | Required. |
Request body
| Field | Type | Notes |
|---|---|---|
label |
string | Free-text identifier shown in the dashboard. |
scopes |
array of string | Replaces the key’s scopes entirely. |
expires_at |
string | A future timestamp to set an expiry, or null to remove one. |
Response 200
The updated key.
| Field | Type | Notes |
|---|---|---|
id |
string | Required. |
tenant_id |
string | Required. |
prefix |
string | Required. 8-char public prefix; safe to store and display. |
scopes |
array of string | Required. |
label |
string | Required. |
last_used_at |
string | |
revoked_at |
string | |
created_at |
string | Required. |
test |
boolean | True for an lk_test_* key: the whole request path runs but a send never reaches the mail server and nothing counts against the account. |
expires_at |
string | When the key stops authenticating. Null means it does not expire, which is how every key behaved before expiry existed. Enforced at authentication, so the key fails the first request after this moment rather than whenever a sweep runs. |
rotated_to |
string | The successor issued by POST /v1/api-keys/{id}/rotate. Set on the PREDECESSOR, so you can see which key replaced this one while both still work through the overlap window. |
Errors: 400, 401, 403, 404, 409
Revoke an API key
DELETE /v1/api-keys/{id} · scope tenant:admin
Soft-deletes (sets revoked_at) on the named key. The row stays for
audit purposes; the key no longer authenticates.
You cannot revoke the key currently being used to make this
call, that would lock you out. Use a different tenant:admin key.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id |
path | string | Required. |
Response 204
Revoked.
Errors: 401, 403, 404, 409
Rotate an API key
POST /v1/api-keys/{id}/rotate · scope tenant:admin
Issues a successor key and puts a short expiry on this one, so both work until the overlap ends. That window is the point: without it, rotation is revocation with extra steps and every caller has to swap credentials in the same instant.
The successor inherits this key’s scopes, its label (the label names
the integration, and the integration has not changed) and its test
flag. Its full secret is in this response and nowhere else.
The response’s expires_at is the predecessor’s deadline, so you
can see from the rotation itself how long you have to cut over.
A key that has already been rotated cannot be rotated again: chaining overlaps would leave several live keys for one integration, which is the opposite of the intent. Rotate the successor instead.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id |
path | string | Required. |
Request body
| Field | Type | Notes |
|---|---|---|
grace_seconds |
integer | How long the old key keeps working. Defaults to 24 hours, which is long enough to cut over without a scramble. Capped at 30 days, because beyond that “rotated” stops meaning anything. |
Response 201
The successor key. Its secret is shown only here; expires_at is the predecessor’s deadline.
Errors: 400, 401, 403, 404, 409