Roles and Permissions

Gravity Rail uses role-based access control (RBAC) to determine what each member can see and do. Permissions are controlled by scopes granted through member roles. If a member lacks a required scope, the corresponding feature is hidden from the sidebar.

Default Roles

New workspaces come with two built-in roles:

Workspace administrators can create custom roles with any combination of scopes via People > Roles.

Scope Hierarchy

Scopes follow a three-level hierarchy:

• admin implies write and read
• write implies read
• read is the base level

Example: Granting members:admin automatically includes members:write and members:read.

Sidebar Permissions

Every sidebar item requires a specific permission scope. Items are completely hidden if the user lacks the scope. If all children of a parent menu are hidden, the parent disappears too.

Top-Level Items

Automation

Knowledge

People

Channels

Developer

Settings

All Settings pages require workspace:admin:

• Workspace
• Milestones
• Billing & Usage
• Features

API Endpoint Permissions

Backend endpoints enforce scope requirements. Self-access patterns allow users to access their own resources without admin scopes.

Data Types vs Records

Important distinction: Data types and records use separate permission namespaces:

• datatypes:* controls access to form schemas (metadata) - does not contain PHI
• records:* controls access to data instances (contains PHI)

Viewing or editing form schemas does not grant access to the actual data records.

Common Endpoint Patterns

Special Cases

• Anonymous members: Viewing anonymous members requires members:admin
• Member deletion: Create/update use members:write, but delete requires members:admin
• Discord/Slack/EHR: All operations require workspace:admin
• Google Calendar integration: Uses calendar scopes (calendars:read/write/admin)

Self-Access Pattern

Many endpoints allow users to access their own resources without admin scopes:

• Viewing own member profile (GET /me)
• Updating own member profile (PUT /me)
• Viewing own chats (chats where owner_id = self)
• Updating own records (records where member_id = self)
• Classifying own phone number

Admin scopes (members:read, chats:read, records:read) are required to access other members' data.

Feature Flags vs Permissions

Some features require both a permission scope and a workspace feature flag:

• Permission scope: Controls whether the user's role allows access
• Feature flag: Controls whether the workspace has the capability enabled

If a feature is disabled at the workspace level, the item appears in the sidebar but is locked. If the user lacks the required permission, the item is completely hidden.

Common Role Configurations

Read-Only Analyst

View data without modification:

• chats:read, members:read, datatypes:read, records:read, files:read, labels:read, analytics:read

Care Coordinator

Manage members and chats, view workflows:

• chats:read, chats:write, members:read, members:write, workflows:read, assignments:read, assignments:write, files:read, labels:read

Workspace Administrator

Full control (same as default Manager role):

• All grantable scopes (see default Manager role)