Authentication

The API authenticates with API keys you create in Settings → API. A key is scoped to one workspace and carries a fixed set of permissions. Keys look like clad_mk_... and are passed as a Bearer token:

POST /graphql HTTP/1.1
Host: clad-server-production.up.railway.app
Authorization: Bearer clad_mk_xxxxxxxxxxxxxxxxxx_...
Content-Type: application/json

Creating a key

In Clad, go to Settings → API (org admins only), then:

1. Enter a key name — a label so you can recognize it later (e.g. Production backend).
2. Pick its permissions:
   • Full access — read and write everything this workspace exposes over the API, including admin-only settings.
   • Read-only — fetch issues, contacts, accounts, articles, and more, but make no changes.
   • Custom — grant exactly the scopes you need (see Scopes & permissions).
3. Click Create key and copy the clad_mk_... secret immediately — it is shown exactly once. Store it in your backend secret manager.

Use the key from server-side code only. Never expose it in a browser, mobile app, or public repo. Revoke a key anytime from the same page; integrations using it stop working immediately.

You don't create a "user" for the key — Clad manages the underlying API principal for you. You just name the key and choose its permissions.

Creating keys programmatically

Org admins can also mint keys with the createApiKey mutation using an admin-scoped key. machineUserId is the API principal a key is attached to; call machineUsers to list existing ones or createMachineUser to make a new one for grouping keys by system.

mutation CreateKey($input: CreateApiKeyInput!) {
  createApiKey(input: $input) {
    apiKey { id keyPrefix scopes }
    secret   # returned once — store it now
    error { code message }
  }
}

{
  "input": {
    "machineUserId": "<machine-user-id>",
    "name": "Production backend",
    "scopes": ["issues:read", "issues:write", "thread:reply"]
  }
}

Revoke a compromised key immediately with revokeApiKey(id).

Legacy keys

Existing REST /v1 keys (clad_live_...) also authenticate against GraphQL, but they are bridged to a single issues:create scope — they can call createIssue and nothing else. To do more, mint a clad_mk_... key with explicit scopes.