Authentication

RawTree Cloud and RawTree BYOC authenticate service API requests with bearer credentials. The service manages API keys and organization identities. RawTree uses SQL users, roles, and grants to enforce database access.

Authorization: Bearer rt_...

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

Credentials across interfaces

The OpenAPI specification lists the service HTTP contracts. Its security schemes distinguish API keys (apiKeyAuth), first-party sessions (bearerAuth), and user OAuth (oauth2). A Bearer header can carry different credential types. The method determines which types it accepts.

See MCP, CLI, and TypeScript SDK for client setup. Service credentials do not become native database passwords. The service resolves the database identity for each request.

User sessions and OAuth

The dashboard and rtree login use first-party user sessions. These sessions follow the user's organization membership. An administrator can manage that organization's resources. A member has the access allowed by each method. The dashboard sends its session cookie. API clients can send the session token in the Authorization: Bearer header. Cookie requests that change state must include an accepted Origin.

External clients use OAuth Authorization Code with PKCE (S256) and the full_access scope. Use the authorization-server metadata at https://api.rawtree.com/.well-known/oauth-authorization-server to discover its endpoints. OAuth permission remains subject to organization membership and method restrictions. Billing, identity administration, OAuth grant management, and service-account deletion require a first-party session where enforced.

# List organizations with a user session or user OAuth access token.
curl -X GET 'https://api.rawtree.com/v1/organizations' \
  -H "Authorization: Bearer $RAWTREE_USER_TOKEN"

For data requests with a user token, pass organization, cluster, and database names. API keys and workload tokens already select an organization and cluster. Their default database can be changed per request.

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, the service uses the API key's stored default database. Creating a key stores the database selected on that request; if no database is selected, the service stores the logical default database. On the shared cluster, the service 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

TRUNCATE TABLE requires write permission: admin, read_write, or write_only. It removes all rows while preserving the table. Database-role keys cannot truncate through the Query API.

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 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 selected database grants, send database_roles instead of permission when creating the key. Use an administrator API key for this request.

curl -X POST 'https://api.rawtree.com/v1/keys?database=analytics' \
  --header "Authorization: Bearer $RAWTREE_API_KEY" \
  --header "Content-Type: application/json" \
  -d '{"name":"event-pipeline","database_roles":["analytics_reader","events_writer"]}'

The response contains the new key's ID and token.

{
  "id": "<key-id>",
  "token": "rt_..."
}

Save the token value as ROLE_API_KEY and the id value as ROLE_KEY_ID.

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.

The service creates a separate RawTree user for the key and activates those roles before it returns the token. The role grants determine which databases, tables, and columns the key can access. Grant changes apply to keys that use those roles. Row policies assigned to those roles filter the rows they can read; use read-only roles for row-restricted keys.

Select the database on each query request, or use the key's stored default. This request selects analytics explicitly.

curl -X POST 'https://api.rawtree.com/v1/query?database=analytics' \
  --header "Authorization: Bearer $ROLE_API_KEY" \
  --header "Content-Type: application/json" \
  -d '{"sql":"SELECT action FROM events"}'

Database-role keys support SQL reads, query formatting, query cancellation, and inserts into existing tables. They can discover their organization and cluster, list and describe tables, and list or invoke handlers when database grants allow it. They do not grant other service management 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

Send the role and grant as separate POST /v1/query requests. Create the key with POST /v1/keys and database_roles. Dropping and recreating a role removes its grants. See restrict an API key, the access-control concepts, and the role and grant references.

Workload identity federation

Exchange your provider's signed workload identity token for a short-lived service access token. No interactive login, client registration, or API key is needed by the workload.

An organization admin first adds an identity provider under Identity providers, then a federation policy under Federation policies on the target cluster. Select the identity provider, allowed audience, exact claim conditions, a user or service-account principal, and either an API permission or existing database roles. Conditions restrict which workloads may authenticate; they do not filter data rows. Database grants and row policies control data access.

Exchange the assertion at the shared API endpoint:

curl -X POST "https://api.rawtree.com/oauth/token" \
  --data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer' \
  --data-urlencode "federation_rule_id=$RAWTREE_FEDERATION_RULE_ID" \
  --data-urlencode "assertion=$PROVIDER_ID_TOKEN"

The response contains access_token, token_type: "Bearer", expires_in and scope. Use the access token in the Authorization: Bearer header on /v1/query and other HTTP API requests permitted by the policy. The policy determines the organization and cluster, so these are not additional exchange parameters.

Tokens last at most 15 minutes and never outlive the provider assertion. Each assertion can be exchanged once per identity provider configuration. Obtain a fresh assertion to renew access or retry a failed exchange; there is no refresh token. Assertions must include iss, sub, aud, iat and exp, have a lifetime of at most one hour, and satisfy every rule condition. Database-role exchanges require more than 30 seconds remaining to provision the database credential.

Disabling, editing or deleting the rule invalidates its existing access tokens. Editing the identity provider, removing the mapped user from the organization or deleting the service account also prevents further access. Requests already authenticated may finish. Workload tokens do not sign into the dashboard or authenticate OTLP gRPC connections.

Workload tokens for hosted MCP

For hosted MCP, include its resource origin in the exchange:

# Exchange a fresh provider assertion for an MCP access token.
curl -X POST 'https://api.rawtree.com/oauth/token' \
  --data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer' \
  --data-urlencode "federation_rule_id=$RAWTREE_FEDERATION_RULE_ID" \
  --data-urlencode "assertion=$PROVIDER_ID_TOKEN" \
  --data-urlencode 'resource=https://mcp.rawtree.com'

Send the returned token as Bearer authentication to https://mcp.rawtree.com/mcp. The resource is the origin, without /mcp. If you omit it, the exchange returns an API token that hosted MCP rejects. The federation rule still controls the principal, cluster, database, and permissions. It does not grant user-level management access.

Test with GitHub Actions

Add the GitHub identity provider. It uses the issuer URL https://token.actions.githubusercontent.com with OIDC discovery. Configure a dedicated rule for the repository and workflow you intend to trust. Match GitHub's actual sub or immutable repository/owner claims; subject formats can vary between repositories. See GitHub's OIDC reference.

The repository includes a manual demo workflow and its Python script. Copy both into the repository trusted by your rule, or run the workflow in that repository if they are already present. Configure the workload-federation-demo GitHub environment with permitted branches and variables RAWTREE_URL, RAWTREE_FEDERATION_RULE_ID and RAWTREE_AUDIENCE. Match the environment subject in your rule. The job requires id-token: write; its destination comes from trusted environment configuration. The script requests a GitHub token, exchanges it, and runs SELECT 42 AS value. It prints the result and keeps both tokens out of its output. CI runs this same script against a real GitHub token and the candidate service build.

A 400 invalid_grant means the assertion could not be accepted: check the issuer, audience, required claims, signing keys, expiry and whether it was already used. A 401 on a subsequent API request indicates an expired or revoked credential. A permission error means authentication succeeded but the rule or database role does not allow the requested operation.

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.