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.

Built-in 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

The name and granted scopes of these five are fixed — the API rejects changes, and the General tab renders them read-only with an explanation. They cannot be deleted either.

To grant a different set of permissions, create a custom role via Members > Roles, where any combination of scopes is allowed.

Everything else about a built-in role stays editable, including its resource access — which workflows, forms, inboxes, calendars, files, folders and sites it can reach. That is usually the reason to open a role at all, so built-in roles open in the normal edit form; only the fixed fields are read-only. Only the workspace-wide scope set is locked.

(Note that "built-in" is unrelated to the role marked as the default for new members — a workspace chooses that separately, and it is often a custom role.)

Cleaning up duplicate built-in roles

Workspaces created by older versions of Gravity Rail can carry the same built-in role under more than one spelling — a manager sitting next to Manager, or an admin left from before Manager existed. Two roles that look alike but grant different things are a real hazard, so the Roles screen surfaces them.

When duplicates exist, administrators (member_roles:admin) see a panel above the roles list listing each duplicate, the role it should fold into, and how many members and references the merge would move. Merging:

1. Moves every member from the duplicate to the built-in role.
2. Moves every reference to it — resource access, site and phone-number signup defaults, agent personas, and any invitation that has not yet been claimed.
3. Deletes the duplicate.

Before confirming you choose what happens to the duplicate's resource access:

• Copy it across (the default choice) — the built-in role gains the duplicate's access, so nobody who held the duplicate loses anything. The dialog states exactly how many resources become newly reachable for people who already hold the built-in role.
• Discard it — migrated members get only what the built-in role already grants. Nothing is widened, but some members may lose access.

The merge is irreversible and audit-logged. Roles suggested from an older name (such as admin) are labelled Review first, because a workspace may have customised that role into something it genuinely relies on — check what it grants before merging. The panel can be minimised, and disappears entirely once the workspace has no duplicates left.

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	Feature Flag
Workflows	workflows:read
Actions	automations:read
Routines	automations:read
Journeys	journeys: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)

For developers

• Member Roles API — create and manage roles and their scopes programmatically