API keys — Reference — Clement docs

List API keys in the workspace

get /v1/api_keys

Lists keys of the calling key's mode (a `cl_test_*` key sees only test keys). Dashboard sessions see both modes.

curl TypeScript

curl -X GET "https://api.clement.so/v1/api_keys" \
  -H "Authorization: Bearer $CLEMENT_API_KEY"

import { Clement } from "@clement/sdk";

const c = new Clement({ apiKey: process.env.CLEMENT_API_KEY! });
const result = await c.apiKeys.list();

Response200

OK

Property	Type	Description
`object` required	enum (1)	`"list"`
`data` required	array<ApiKey>
`has_more` required	boolean
`next_cursor` required	string \| null

Example response

{
  "object": "list",
  "data": [
    {
      "id": "key_01HZ8X3J9K7P2QV6R5N4M3T2LC",
      "object": "api_key",
      "name": "Production CRM sync",
      "mode": "live",
      "scope": "write",
      "last_four": "x4Y9",
      "auto_confirm": false,
      "created_at": "2026-04-15T09:00:00Z",
      "last_used_at": "2026-04-29T15:42:00Z",
      "revoked_at": null
    }
  ],
  "has_more": false,
  "next_cursor": "string"
}

Errors

400 Invalid request
401 Authentication failed
403 Insufficient scope
404 Not found

See Errors for the full envelope and per-code reference.

Create an API key (secret returned once)

post /v1/api_keys

An API key can only create keys of its own mode: a `cl_test_*` admin key can't mint `cl_live_*` keys (403). Dashboard sessions can create either.

curl TypeScript

curl -X POST "https://api.clement.so/v1/api_keys" \
  -H "Authorization: Bearer $CLEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
      "name": "Alice Liddell",
      "scope": "read",
      "mode": "live",
      "auto_confirm": false
    }'

import { Clement } from "@clement/sdk";

const c = new Clement({ apiKey: process.env.CLEMENT_API_KEY! });
const result = await c.apiKeys.create({
  "name": "Alice Liddell",
  "scope": "read",
  "mode": "live",
  "auto_confirm": false
});

Request body

Property	Type	Description
`name` required	string
`scope`	enum (3)	`"read""write""admin"`
`mode`	enum (2)	Defaults to the calling key's mode. An API key may only create keys of its own mode (403 otherwise); dashboard sessions may create either, defaulting to `live`. `"live""test"`
`auto_confirm`	boolean

Response201

Created — `secret` is in the response and never returned again

Property	Type	Description
`id` required	string	Example: `"key_AM788072KD0X99RP8HK5AH0000"`
`object` required	enum (1)	`"api_key"`
`name` required	string
`mode` required	enum (2)	`"live""test"`
`scope` required	enum (3)	`"read""write""admin"`
`last_four` required	string
`auto_confirm` required	boolean
`created_at` required	string (date-time)
`last_used_at` required	string (date-time) \| null
`revoked_at` required	string (date-time) \| null
`secret` required	string	Example: `"cl_live_a1b2c3d4e5f6…"`

Example response

{
  "id": "key_01HZ8X3J9K7P2QV6R5N4M3T2LC",
  "object": "api_key",
  "name": "Production CRM sync",
  "mode": "live",
  "scope": "write",
  "last_four": "x4Y9",
  "auto_confirm": false,
  "created_at": "2026-04-15T09:00:00Z",
  "last_used_at": "2026-04-29T15:42:00Z",
  "revoked_at": null
}

Errors

400 Invalid request
401 Authentication failed
403 Insufficient scope
404 Not found

See Errors for the full envelope and per-code reference.

Revoke an API key

delete /v1/api_keys/{id}

API keys can only revoke keys of their own mode; others return 404. Dashboard sessions can revoke either.

curl TypeScript

curl -X DELETE "https://api.clement.so/v1/api_keys/obj_01HZ8X3J9K7P2QV6R5N4M3T2L1" \
  -H "Authorization: Bearer $CLEMENT_API_KEY"

import { Clement } from "@clement/sdk";

const c = new Clement({ apiKey: process.env.CLEMENT_API_KEY! });
const result = await c.apiKeys.delete("obj_01HZ8X3J9K7P2QV6R5N4M3T2L1");

Path parameters

id string required

Query parameters

confirm string

Response200

Revoked

Property	Type	Description
`id` required	string	Example: `"key_AM788072KD0X99RP8HK5AH0000"`
`object` required	enum (1)	`"api_key"`
`name` required	string
`mode` required	enum (2)	`"live""test"`
`scope` required	enum (3)	`"read""write""admin"`
`last_four` required	string
`auto_confirm` required	boolean
`created_at` required	string (date-time)
`last_used_at` required	string (date-time) \| null
`revoked_at` required	string (date-time) \| null

Example response

{
  "id": "key_01HZ8X3J9K7P2QV6R5N4M3T2LC",
  "object": "api_key",
  "name": "Production CRM sync",
  "mode": "live",
  "scope": "write",
  "last_four": "x4Y9",
  "auto_confirm": false,
  "created_at": "2026-04-15T09:00:00Z",
  "last_used_at": "2026-04-29T15:42:00Z",
  "revoked_at": null
}

Errors

400 Invalid request
401 Authentication failed
403 Insufficient scope
404 Not found

See Errors for the full envelope and per-code reference.

Rotate an API key (issues a new secret, revokes the old one)

post /v1/api_keys/{id}/rotate

Confirmation guard: `?confirm=true` required (or a calling key with `auto_confirm: true`). Without it returns 400 with `code: confirmation_required` — rotation invalidates the old secret immediately and any caller still using it will start getting 401s. API keys can only rotate keys of their own mode; others return 404.

curl TypeScript

curl -X POST "https://api.clement.so/v1/api_keys/obj_01HZ8X3J9K7P2QV6R5N4M3T2L1/rotate" \
  -H "Authorization: Bearer $CLEMENT_API_KEY"

import { Clement } from "@clement/sdk";

const c = new Clement({ apiKey: process.env.CLEMENT_API_KEY! });
const result = await c.apiKeys.rotate("obj_01HZ8X3J9K7P2QV6R5N4M3T2L1");

Path parameters

id string required

Query parameters

confirm string

Response200

Rotated

Property	Type	Description
`id` required	string	Example: `"key_AM788072KD0X99RP8HK5AH0000"`
`object` required	enum (1)	`"api_key"`
`name` required	string
`mode` required	enum (2)	`"live""test"`
`scope` required	enum (3)	`"read""write""admin"`
`last_four` required	string
`auto_confirm` required	boolean
`created_at` required	string (date-time)
`last_used_at` required	string (date-time) \| null
`revoked_at` required	string (date-time) \| null
`secret` required	string	Example: `"cl_live_a1b2c3d4e5f6…"`

Example response

{
  "id": "key_01HZ8X3J9K7P2QV6R5N4M3T2LC",
  "object": "api_key",
  "name": "Production CRM sync",
  "mode": "live",
  "scope": "write",
  "last_four": "x4Y9",
  "auto_confirm": false,
  "created_at": "2026-04-15T09:00:00Z",
  "last_used_at": "2026-04-29T15:42:00Z",
  "revoked_at": null
}

Errors

400 Invalid request
401 Authentication failed
403 Insufficient scope
404 Not found

See Errors for the full envelope and per-code reference.