API Keys API
API endpoints for managing API keys.
API Keys API
Manage API keys for programmatic access to SidClaw. Keys are scoped to a tenant and can have specific permissions.
List API Keys
GET /api/v1/api-keysAuthentication: Session (admin role required)
Response:
{
"data": [
{
"id": "key_abc123",
"name": "Production SDK",
"prefix": "ai_1234",
"scopes": ["evaluate", "traces:read", "traces:write"],
"last_used_at": "2026-03-23T12:00:00.000Z",
"created_at": "2026-03-20T10:00:00.000Z",
"expires_at": null
}
]
}Create API Key
POST /api/v1/api-keysAuthentication: Session (admin role required)
Request body:
{
"name": "Production SDK",
"scopes": ["evaluate", "traces:read", "traces:write"],
"expires_at": "2027-03-23T00:00:00.000Z"
}| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Human-readable name |
scopes | string[] | Yes | At least one of: evaluate, agents:read, agents:write, agents:lifecycle, policies:read, policies:write, traces:read, traces:write, approvals:read, approvals:write, admin. See Authentication — API Key Scopes |
expires_at | string | No | ISO 8601 expiration date (null for no expiry) |
Response:
{
"data": {
"id": "key_abc123",
"name": "Production SDK",
"key": "ai_full_key_shown_only_once",
"prefix": "ai_1234",
"scopes": ["evaluate", "traces:read", "traces:write"],
"created_at": "2026-03-23T10:00:00.000Z"
}
}The full API key is returned only once at creation time. Store it securely.
Delete API Key
DELETE /api/v1/api-keys/:idAuthentication: Session (admin role required)
Response: 204 No Content
Rotate API Key
Generate a new key value while keeping the same key ID, name, and scopes.
POST /api/v1/api-keys/:id/rotateAuthentication: Session (admin role required)
Response:
{
"data": {
"id": "key_abc123",
"key": "ai_new_key_shown_only_once",
"prefix": "ai_5678"
}
}The old key is immediately invalidated.
Using API Keys
Include the key in the Authorization header:
curl -H "Authorization: Bearer ai_your_key_here" \
https://api.sidclaw.com/api/v1/agentsOr in the SDK:
import { AgentIdentityClient } from '@sidclaw/sdk';
const client = new AgentIdentityClient({
apiKey: 'ai_your_key_here',
agentId: 'ag_abc123',
});from sidclaw import SidClaw
client = SidClaw(
api_key="ai_your_key_here",
agent_id="ag_abc123",
)Scopes
| Scope | Permissions |
|---|---|
evaluate | Call POST /api/v1/evaluate |
agents:read / agents:write | Read / create and edit agents |
agents:lifecycle | Suspend, revoke, reactivate agents |
policies:read / policies:write | Read / create, edit and delete policies |
traces:read / traces:write | Read traces / record outcomes and telemetry |
approvals:read / approvals:write | Read approvals / approve and deny |
admin | Full access including key management |
See Authentication — API Key Scopes for the endpoint-by-endpoint mapping.