Roles and Permissions

A Member’s role grants Workspace-wide scopes, such as permission to edit phone routing or send from Inboxes. Ownership, explicit sharing, and record scope also determine access. A missing sidebar scope can hide a management screen without preventing a Member from using their own records or starting an available Workflow.

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	Limited workspace participation	agents:read, dm:read, dm:write, devices:write	Basic Agent and direct-message access
Agent	AI agent members	None	Reserved for agent members: Agents operate via tool-level scope checks rather than role-granted scopes, and only an Agent can hold this role
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 Agent role and the four human roles are not interchangeable: an Agent member can hold the Agent role (or a custom role), and a person can hold any built-in role except Agent. The API refuses the mismatch with a 400 whether it comes from a member record or an invitation; a member import instead fails the affected row (an Agent role named as the import's create-new role fails every row that would be created). To give an Agent a different permission set, create a custom role.

Choose Manager for colleagues who need to manage workspace settings, Members, and Workflows. Choose User when that person only needs the more limited access listed above.

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: the Sites it may use (the Site's audience) and its access to specific Files and Folders. Built-in roles open in the normal edit form; only the fixed fields are read-only.

(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.

If the target is built-in Manager or User, every human Member on the duplicate, including archived Members, must have an Account before the merge. The merge is refused otherwise; review those Members and reconcile their Accounts or change their roles explicitly, then retry. No Member is reassigned automatically after a refusal.

The same holds for the member-type pairing: a duplicate holding an Agent and a human side by side cannot be merged onto a human built-in or onto the Agent role, because the merge would pair one of them with a role they cannot hold. Move those Members to the right role first, or merge onto a custom role. The merge is refused with the offending direction named; nothing is reassigned.

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.

What a role reaches

Forms, Workflows, Inboxes, and Calendars no longer have per-resource role permission tables. Configure Workspace scopes on a custom role; configure a Member Role Gate on a Workflow when entry should be restricted. Files, Folders, and Site audiences retain their role access settings.

Scopes decide what a role reaches beyond a Member's own data:

• Forms: every Member works with their own records. Every Member can read the records of a workspace-wide Form; records:write allows creating, editing, and deleting them. Read another Member’s records with records:admin, a read sharing grant, or a relationship with chart access. Edit them with records:admin or a write grant; creating a record for another Member requires records:write. An Admin only Form’s records require records:admin; its owner and Members with datatypes:admin can still manage its schema.
• Workflows: every Member can start a Workflow unless the Workflow has a Member Role Gate, which lists the roles allowed in and what everyone else is told. Set it on the Workflow, not on the role.
• Inboxes: ownership or an explicit Inbox grant can provide access to one Inbox; inboxes:read, inboxes:write, and inboxes:admin apply Workspace-wide. See Email Inboxes.
• Phone numbers: phones:read to view lines, phones:write to create or edit them, and phones:admin to delete them. Selecting a routing owner or a role for new callers does not grant these scopes.
• Calendars: calendars:read to view and book, calendars:write to manage.
• Sites: the Sites tab lists the Sites this role may use.

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

Analyze

Sidebar Item	Required Scope	Feature Flag
Metrics	workspace:read
Experiments	experiments: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; every Member reads workspace-wide Forms
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	Owners manage their own Calendars
Inboxes	inboxes:read	inboxes:write (create/edit/automated sending)	inboxes:admin	Ownership supplies object access; Compose, Send, and Reply still require inboxes:admin
Workflows	workflows:read	workflows:write	workflows:admin	Any Member can start a Workflow that has no Member Role Gate
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

Access to another Member’s profile, Chats, or records depends on the resource’s own policy. Read scopes do not grant every action: records may also be shared explicitly or reached through a relationship with chart access. See Forms.

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