Authentication

CluGTM uses standard HTTP Bearer authentication. Every request to the v1 API (/api/v1/public/*) must include an Authorization header with a valid clapi_ API key.

Authorization: Bearer clapi_your_api_key_here

The same key works on the v2 API. v1 endpoints don’t check scopes; v2 endpoints each require a scope, such as enrich:write.

Key basics

Creating a key

1. Open app.clugtm.com  and go to Settings → API keys.
2. In the Create API key section, optionally fill in:
   • Name: a label so you can tell keys apart, for example “CI integration”.
   • Expiry: a date and time after which the key stops working.
3. Click Create API key.
4. Copy the key from the New API key box (“copy now, it won’t be shown again”).

If you already have 10 active keys, creation fails with “Maximum active API keys reached (10). Revoke an existing key before creating a new one.”

If your plan doesn’t include API access, the page shows The CluGTM API. upgrade card instead of the form. During the Pro trial, keys can’t be created; pick a plan that includes the API first.

Viewing and auditing keys

The Your API keys section lists every key you created in this workspace, with an N active count. For each key you see:

• its name (or “Unnamed key”) and an Active or Revoked badge,
• the first characters and last 4 characters of the key,
• Created, Last used and Expires dates, and the number of requests.

Click View requests to open the key’s 50 most recent requests (method, path, status code, duration and time). Click Hide requests to close it.

To list keys or pull usage reports from code, use the v2 endpoints GET /api/v2/api-keys and GET /api/v2/usage (scope admin:api_keys). See v2 authentication.

Revoking keys

• Revoke next to a key revokes that key.
• Revoke all revokes every key you have in this workspace (useful if you suspect a leak).

Revocation takes effect immediately and can’t be undone. Create a new key if you need access again.

Using a key

curl https://api.cleanlist.ai/api/v1/public/auth/validate-key \
  -H "Authorization: Bearer clapi_your_api_key"

import os
import requests
 
API_KEY = os.environ["CLEANLIST_API_KEY"]
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
 
response = requests.get(
    "https://api.cleanlist.ai/api/v1/public/auth/validate-key",
    headers=HEADERS,
)
response.raise_for_status()
print(response.json())

const API_KEY = process.env.CLEANLIST_API_KEY;
const HEADERS = { Authorization: `Bearer ${API_KEY}` };
 
const response = await fetch(
  "https://api.cleanlist.ai/api/v1/public/auth/validate-key",
  { headers: HEADERS },
);
if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());

GET /api/v1/public/auth/validate-key

Confirms a key works and shows who it belongs to. It costs no credits and counts toward the rate limit.

{
  "valid": true,
  "user_id": "user_2abcJANEdoe456",
  "organization_id": "org_2acmeIO789xyz"
}

Security best practices

• Never commit clapi_ keys to source control.
• Keep keys in a secret manager (AWS Secrets Manager, Doppler, 1Password, Vault) or environment variables.
• Use a separate key per environment (development, staging, production) and give each a Name.
• Set an Expiry on keys used for short-lived jobs.
• Check Last used and View requests for unexpected activity, and Revoke a key the moment it leaks.

Authentication errors

Related

• Legacy API (v1) overview
• Errors and rate limits
• API quickstart
• v2 authentication and scopes