Authentication

RawTree API requests use bearer authentication.

Authorization: Bearer rt_...

Use rtree login for interactive CLI workflows. Use API keys for agents, scripts, services, and CI.

Create an API key

rtree key create --name my-agent --permission read_write

Every API key belongs to one organization and one cluster. It is not tied to a database. For keys created with permission, that permission applies to every current and future database in the cluster. Keys created with database_roles are limited by those roles' grants.

Choose the database on each data-plane request with ?database=<name> or the x-rawtree-database header. If neither is provided, RawTree uses the API key's stored default database. Creating a key stores the database selected on that request; if no database is selected, RawTree stores the logical default database. On the shared cluster, RawTree maps the logical name to the organization's isolated rt_<organization_id>_<database> namespace.

Expiration

Set expires_at when calling POST /v1/keys to create an expiring key:

{
  "name": "reporting",
  "permission": "read_only",
  "expires_at": "2027-01-01T00:00:00Z"
}

The timestamp must be in the future and include a timezone (RFC 3339). Omit expires_at or set it to null for a key that never expires. Existing keys have no expiration. This applies to both permission-based and database-role keys. Creation and list responses include expires_at as a UTC timestamp or null.

At or after expiration, new requests fail authentication (HTTP 401 or gRPC UNAUTHENTICATED), including when the key is cached. Requests already authenticated may finish. Expired keys remain visible and can be deleted. Expiration is fixed at creation; create a replacement key to choose a different expiration.

Permissions

API keys can read full details for their bound organization and cluster with GET /v1/organizations and GET /v1/clusters. Each returns one entry using the same response schema as user credentials, including organization plan/avatar metadata and cluster status, resources, and storage configuration. Organization membership role is null for API keys; users retain their membership role. User credentials list all accessible resources. An explicit organization must match the API key's organization name.

API keys cannot read account, membership, billing, or cluster-management endpoints. An admin API key can manage databases and API keys in its own cluster.

Existing database roles

To restrict a key to specific ClickHouse grants, send database_roles instead of permission when creating the key:

curl -X POST "$RAWTREE_URL/v1/keys" \
  -H "Authorization: Bearer $RAWTREE_ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"event-pipeline","database_roles":["analytics_reader","events_writer"]}'

Provide exactly one access field. database_roles accepts 1–32 distinct names of roles that already exist on the key's cluster. Assigning roles requires an organization administrator or an admin API key. Role names are case-sensitive.

RawTree creates a separate database user for the key and activates those roles before returning the token. ClickHouse determines which databases, tables, and columns it can access. Changes to the roles' grants apply to keys using them. Row policies assigned to those roles filter the rows they can read; use read-only roles for row-restricted keys.

This mode currently supports SQL reads through POST /v1/query, cancellation through POST /v1/query/cancel, and inserts into existing tables through POST /v1/tables/{table}. Database roles do not grant RawTree management or metadata API access. Inserts do not automatically create tables. Role creation and grant management happen separately from key creation.

Custom-key create/list responses contain database_roles and omit permission. Permission-based keys continue to use the permission field. Deleting a custom key removes its database user and preserves the assigned roles.

Create a data role through the Query API

Organization administrators and admin API keys can send these statements to POST /v1/query, one statement per request:

CREATE ROLE analytics_reader

GRANT SELECT ON default.events TO analytics_reader

The Query API supports CREATE ROLE, DROP ROLE [IF EXISTS], and GRANT SELECT / GRANT INSERT to an existing role. Grants can name columns, combine SELECT and INSERT, or use database.* / *.*. RawTree applies each operation across the selected cluster. An explicit ON CLUSTER 'default' is also accepted. Other clusters, database-user grants, role inheritance, delegation options, and other role-management statements are not supported through this API.

Create the role, apply its grants, then issue the key with database_roles. These are separate operations: if a grant fails, the role and earlier grants remain. Correct and retry the failed grants before creating the key. An existing role is never replaced by CREATE ROLE.

To remove a role, send:

DROP ROLE IF EXISTS analytics_reader

Each request can drop one role. IF EXISTS succeeds even if the role is already absent; without it, a missing role returns an error. Dropping a role removes its grants from the database users that used it, including existing API keys. It does not delete the keys themselves. With explicit ON CLUSTER 'default', use DROP ROLE IF EXISTS so replicas can complete after another replica has already removed the role. Omitting ON CLUSTER is sufficient for replicated role storage.

Recommendations

• Use read_write for agents that ingest and query.
• Use read_only for dashboards, audits, and validation jobs.
• Use write_only for event producers.
• Use admin only for database lifecycle, key management, and destructive data operations.

Environment variables

export RAWTREE_API_KEY=rt_...
export RAWTREE_DATABASE=analytics
export RAWTREE_ORG=team_alpha

The CLI reads RAWTREE_API_KEY before saved local credentials.