Roles and Permissions

The platform uses role-based access control (RBAC) to govern what authenticated users can do. Every action in the platform is gated by a permission, and permissions are grouped into roles.

Permission format

Permissions follow a consistent resource:action pattern:

collections:read
flows:execute
agents:update
integrations:delete

Common actions include:

Built-in roles

The platform provides three built-in roles:

Admin

Full access to all resources in the organization and its spaces.

• Manage members and roles
• Create and configure spaces
• Install and configure apps
• Access all data and settings

Member

Standard access for day-to-day work within assigned spaces.

• Read and write collections, flows, agents
• Execute flows and interact with agents
• Use installed integrations
• Cannot manage organization settings or members

Guest

Limited, read-only access.

• View collections and records
• Read conversations
• Cannot modify resources or execute actions

Role assignment

Roles are assigned at two levels:

A user can hold different roles in different spaces. Organization-level roles cascade down to all spaces unless overridden.

Custom roles

Beyond the built-in roles, administrators can define custom roles that combine specific permissions:

1. Define the role — give it a name and select the permissions it should include
2. Assign the role — attach it to users at the organization or space level

Custom roles are useful for scenarios like:

• A "viewer" who can read collections but not execute flows
• A "flow operator" who can execute flows but not modify them
• An "integration manager" who can manage connections but not access data

Service permissions

Apps, agents, and integrations authenticate as service accounts. Each service account receives permissions based on the app's declared requirements:

• An app that needs to read collections will have collections:read
• An agent that executes flows will have flows:execute
• An integration that writes records will have collections:create and collections:update

Service permissions are granted at install time and scoped to the space where the app is installed.

Permission checks

The platform evaluates permissions on every API request:

1. Identify the user — resolve the authenticated identity
2. Resolve roles — load all roles for the target organization and space
3. Aggregate permissions — combine permissions from all assigned roles
4. Check the required permission — verify the request's required permission is in the set

If the required permission is missing, the request is denied with a 403 Forbidden response.

Related concepts

• Authentication — how users prove their identity
• API Keys — programmatic access with scoped permissions
• Organizations and Spaces — the hierarchy where roles apply