Resource model

RawTree contains databases, tables, users, roles, and other database entities. RawTree Cloud and RawTree BYOC organize access to database clusters through service organizations and memberships.

Different entities belong to different layers:

The service can create and manage database objects. For example, creating a database-role API key provisions a database user with the selected roles. The service owns the credential lifecycle, while RawTree (the database) enforces the grants.

Organizations and members

An organization groups its members and clusters. A member has the admin or member membership level. Organization management requires a signed-in user. API keys can list their bound organization, but they are not organization members and return a null membership role.

# List organizations for your signed-in user.
# RAWTREE_SESSION_TOKEN holds your user session token.
curl -X GET "https://api.rawtree.com/v1/organizations" \
  -H "Authorization: Bearer $RAWTREE_SESSION_TOKEN"

# List organizations for your signed-in user.
# Use a user session from rtree login.
rtree organization list --api-url https://api.rawtree.com --json

An organization admin can create clusters and manage members. Members can use resources that their access permits. See Manage members.

Clusters

A cluster contains databases and their tables.

# List clusters in team-alpha with your user session token.
curl -X GET "https://api.rawtree.com/v1/clusters?organization=team-alpha" \
  -H "Authorization: Bearer $RAWTREE_SESSION_TOKEN"

# List clusters in team-alpha with your signed-in user.
rtree cluster list --org team-alpha --api-url https://api.rawtree.com --json

The sizes method of the cluster API returns available replica sizes for provisioning. Each size reports CPU cores and memory per replica. The API also returns minimum and maximum replica counts; these values can vary by environment.

# List available replica sizes and replica limits.
# This endpoint requires a user session or user OAuth token.
curl -X GET "https://api.rawtree.com/v1/clusters/sizes" \
  -H "Authorization: Bearer $RAWTREE_SESSION_TOKEN"

# List available replica sizes and replica limits.
# Use a user session from rtree login.
rtree cluster sizes --api-url https://api.rawtree.com --json

An admin can stop a cluster and resume it later. A confirmed paused cluster returns 409 with cluster_paused for data requests. Cluster management routes remain available while the cluster is paused.

Databases and tables

Each cluster has databases. The API key's cluster scope limits which databases and tables a given API key can reach.

# List databases in the API key's cluster.
# Use a key with read permission.
curl -X GET "https://api.rawtree.com/v1/databases" \
  -H "Authorization: Bearer $RAWTREE_API_KEY"

# List databases in the API key's cluster.
# Use a key with read permission.
rtree database list --api-url https://api.rawtree.com --json

-- List databases visible to the current database user.
SELECT name
FROM system.databases
ORDER BY name;

Aside from user generated databases, RawTree exposes metadata and system telemetry in the system database, which is protected from deletion.

Tables belong to a database. A table's columns and data are available through the Query API when the key has the required permission.

# List tables in the analytics database.
curl -X GET "https://api.rawtree.com/v1/tables?database=analytics" \
  -H "Authorization: Bearer $RAWTREE_API_KEY"

# List tables in the analytics database.
rtree table list --database analytics --api-url https://api.rawtree.com --json

-- List tables in the analytics database.
SELECT name
FROM system.tables
WHERE database = 'analytics'
ORDER BY name;

Bear in mind the read-only API-key database role has SELECT grants on *.* and can query system tables. See API reference and Monitor usage.

User accounts and service accounts

A user account represents a person. The user signs in to RawTree Cloud or RawTree BYOC and accesses organizations through their memberships. The dashboard, CLI user sessions, and user OAuth tokens act on behalf of that person.

A service account represents an application, agent, or automated job within one organization. It uses API keys or workload federation instead of an interactive sign-in. Organization admins manage these accounts.

A service account's API keys retain their own permissions or database roles. They remain valid if the person who created them leaves the organization. Deleting the service account revokes its keys. Personal keys instead depend on the owner's organization membership.

See Query identity in the database for how these credentials map to database users and query logs.

API keys and cluster-scoped objects

An API key is bound to an organization and cluster. It can also store a default database. The key does not grant organization membership or access to cluster management routes.

# List API keys in the current key's cluster.
# RAWTREE_API_KEY must hold an admin API key.
# The response includes key hints, not complete secrets.
curl -X GET "https://api.rawtree.com/v1/keys" \
  -H "Authorization: Bearer $RAWTREE_API_KEY"

# List API keys in the current key's cluster.
# RAWTREE_API_KEY must hold an admin API key.
# The response includes key hints, not complete secrets.
rtree key list --api-url https://api.rawtree.com --json

Cluster-scoped objects use the organization and cluster as their scope. For example, connectors and workflows require those values when you list or manage them. This keeps their resources separate across clusters.

See API keys, connectors, and workflows.

Related

• Storage and compute
• Access control