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 five built-in roles:

Role	Purpose	Granted Scopes	Notes
Manager	Full workspace access	All grantable scopes (full read/write/admin)
Platform Support	Gravity Rail support staff access	All grantable scopes (mirrors Manager)	Assigned by Gravity Rail support staff only; not available to workspace operators
User	Standard workspace member	agents:read, dm:read, dm:write
Agent	AI agent members	None	Agents operate via tool-level scope checks rather than role-granted scopes
External	Untrusted external members	None	External members access their own assignments and chats via member-scoped context; role-granted scopes are workspace-wide and inappropriate for untrusted members

Workspace administrators can create custom roles with any combination of scopes via Members > 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

Sidebar Item	Required Scope	Notes
Dashboard	None	Visible to all workspace members
Chats	chats:read

Automation

Sidebar Item	Required Scope
Workflows	workflows:read
Actions	automations:read
Routines	automations:read

Knowledge

Sidebar Item	Required Scope	Feature Flag
Forms	datatypes:read
Files	files:read
Labels	labels:read
Calendars	calendars:read	Calendar

Members

The Members section is visible when you hold at least one of these scopes; each view inside it requires its own scope. (Supervisors are managed on Settings → Toolkits and require agents:read there.)

Sidebar Item	Required Scope	Feature Flag
Members (and member views)	members:read
Agents	agents:read
Operator groups	operator:read	Operators
Qualifications	members:admin
Roles	member_roles:read

Channels

Sidebar Item	Required Scope	Feature Flag
Phone	phones:read	Phone
Inboxes	inboxes:read	Email
Sites	sites:read	Sites
Discord	workspace:admin	Discord
Slack	workspace:admin	Slack
EHR	workspace:admin	EHR / FHIR

Developer

Sidebar Item	Required Scope
Apps	apps:read
Toolkits	apps:read
Webhook Logs	webhooks:read

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

Endpoint Pattern	Read	Create/Update	Delete	Self-Access
Data Types (Forms)	datatypes:read	datatypes:write	datatypes:admin	N/A
Data Records	records:read	records:write	records:admin	Users can view/edit their own records
Members	members:read	members:write	members:admin	Users can view/edit their own profile
Chats	chats:read	chats:write	chats:admin	Users can access their own chats
Files	files:read	files:write	files:admin	N/A
Calendars	calendars:read	calendars:write	calendars:admin	N/A
Folders	files:read	files:write	files:admin	N/A

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)