Create and save a key
Open Settings → Developer & API in the account/workspace that will run the tool.
Choose a descriptive name, select the required scopes, and set an expiration if appropriate
Use Read-only MCP for an MCP-only connection.
Create the key and copy the displayed secret immediately
It is shown once. Store it in a secret manager or the environment that launches the tool.
Make one permitted request or connect the tool, then check the key's Last used value
Keep production automation keys separate from a personal development key.
How scopes match a request
The first resource after /api/v1 determines the scope family. Both singular and plural resource spellings are accepted. GET uses read, POST uses create, PATCH/PUT use write, and DELETE uses delete. MCP is the exception: its HTTP POST transport uses mcp:read.
An annotation route nested under /projects belongs to the project scope family, not annotation. A build route nested under /projects also uses project scopes, not build:create.
| Request | Required API-key scope |
|---|---|
| GET /api/v1/projects/:projectId/annotations | project:read |
| PATCH /api/v1/projects/:projectId/annotations/:annotationId | project:write |
| POST /api/v1/projects/:projectId/annotations/:annotationId/ai/retry | project:create |
| GET /api/v1/annotations/:annotationId/diff | annotation:read |
| POST /api/v1/webhooks/outbound | webhooks:create |
| PATCH /api/v1/webhooks/outbound/:webhookId | webhooks:write |
| DELETE /api/v1/webhooks/outbound/:webhookId | webhooks:delete |
| POST /api/v1/sdk/deployments | sdk:create |
| POST /api/v1/mcp | mcp:read |
Choose a scope recipe for your tool
A wildcard such as project:* grants all actions in that family. Avoid * for a tool that only reads. If the scope picker does not offer a needed action, use its custom scope input rather than selecting an unrelated family.
| Task | Start with |
|---|---|
| Read Claron issues through MCP | mcp:read only, plus an eligible project role. See MCP setup. |
| Browse projects and CLI issue evidence | project:read and annotation:read. |
| CLI status changes / investigation actions | Add project:write for PATCH and project:create for POST actions actually used. The role may still require approval. |
| Upload a frontend SDK deployment | sdk:create and access to the target project; configure only in the build environment. |
| Manage outbound webhooks | webhooks:read, webhooks:create, webhooks:write, and webhooks:delete as needed, plus workspace/project webhook authority. |
| Activate an extension device | extension:create; a read-only MCP key cannot activate a broader device token. |
Dedicated SDK credentials
For a separate SDK-only credential, POST /api/v1/sdk/credentials with a name and optional expiresAt while authenticated with a permitted Claron account. Store the returned key once; it has SDK creation scope. Revoke it with DELETE /api/v1/sdk/credentials/:credentialId using the owning account.
A developer key with sdk:create is the simpler Settings-based path for build configuration. It does not complete missing manifest/upload configuration by itself; read the frontend SDK limitations before expecting source-map upload.
Rotate, revoke, and troubleshoot
Create or rotate the credential, save the new secret, and update each consuming secret store or client.
Test the new credential with a permitted request
Revoke the previous key when migration is complete; a rotated/revoked secret must no longer be used.
For 401, check the Authorization: Bearer header, secret value, expiry, and revocation state.
For 403, check both the route's scope family and the account's effective permissions
For plan restrictions, check Billing; a wider key does not change the plan or project role.