Lockally

      Use your API key in the examples

      Replaces lk_live_… in the code samples on this site so you can copy and run them. It is stored in this browser only and is never sent anywhere, including to Ask AI.

      It will be visible on the page. Use a test key if you are sharing your screen or taking screenshots.

      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