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: the key's permission applies to every current and future database in that cluster.

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.

Permissions

These permissions authorize database and data operations only. API keys cannot read account, organization, membership, billing, or cluster-management endpoints. The two control-plane exceptions are explicit: an admin API key can manage databases and API keys in its own cluster.

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.