API keys
API keys API methods, requests, and responses for RawTree Cloud and RawTree BYOC.
API keys
API keys need admin permission to manage keys. User requests follow organization membership and key access rules.
GET /v1/keys
List API keys for the current cluster. Requires an admin API key or JWT.
Use an API key, a permitted workload token, or a user bearer token. Database-role keys support only the operations listed in Authentication.
Request:
# List all API keys for a cluster.
curl -X GET "https://api.rawtree.com/v1/keys" \
-H "Authorization: Bearer $RAWTREE_API_KEY"Expected response: HTTP 200.
{
"keys": [
{
"id": "11111111-1111-4111-8111-111111111111",
"token": "...abcd1234",
"name": "reporting",
"principal_type": "user",
"principal_id": "11111111-1111-4111-8111-111111111111",
"expires_at": null,
"permission": "read_only",
"database": {
"name": "analytics"
},
"created_at": "2026-11-09T10:00:00Z"
}
]
}Errors: 401, 403. See API errors.
POST /v1/keys
Create a cluster-wide API key. Requires an admin API key or JWT. The database
selected on this request is stored as the key's default for later requests that
omit a database selector; if none is selected, the service stores default.
{ "name": "my-agent", "permission": "read_write" }Valid permissions:
adminread_writewrite_onlyread_only
Use an API key, a permitted workload token, or a user bearer token. Database-role keys support only the operations listed in Authentication.
Parameters:
| Field | Location | Type | Required | Notes |
|---|---|---|---|---|
principal_type | body | null or PrincipalType | No | — |
principal_id | body | string or null | No | — |
expires_at | body | string or null | No | Expiration instant in RFC 3339 format. Omitted or null means never. |
name | body | string | Yes | — |
permission | body | null or PermissionLevel | No | — |
database_roles | body | array or null | No | Existing ClickHouse roles. Mutually exclusive with permission. |
Request:
# Create a new API key for a cluster.
curl -X POST "https://api.rawtree.com/v1/keys?database=analytics" \
-H "Authorization: Bearer $RAWTREE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "reporting",
"permission": "read_only"
}'Expected response: HTTP 201.
{
"id": "11111111-1111-4111-8111-111111111111",
"token": "rt_REPLACE_WITH_RETURNED_TOKEN",
"name": "reporting",
"principal_type": "user",
"principal_id": "11111111-1111-4111-8111-111111111111",
"expires_at": null,
"permission": "read_only",
"database": {
"name": "analytics"
}
}Errors: 400, 401, 403. See API errors.
DELETE /v1/keys/{id_or_token}
Delete an API key by UUID or full rt_... token.
Use an API key, a permitted workload token, or a user bearer token. Database-role keys support only the operations listed in Authentication.
Request:
# Permanently delete an API key (cannot be undone).
curl -X DELETE "https://api.rawtree.com/v1/keys/11111111-1111-4111-8111-111111111111" \
-H "Authorization: Bearer $RAWTREE_API_KEY"Expected response: HTTP 200.
{
"deleted": true
}Errors: 400, 401, 403. See API errors.