RBAC

Role-based access control. Permission keys are declared in the manifest. Roles and assignments are managed at runtime via the API or Studio.

How It Works

The manifest declares permission keys — named capabilities like contacts.read or deals.delete. At runtime, you create roles, attach permission keys to them, and assign roles to users. A user's effective permissions are the union of all permission keys from all their assigned roles.

Four concepts:

• Permission keys: declared in the manifest. Define what actions exist (e.g. contacts.read, invoice.create). Follow the entity.action convention. See the manifest reference for the full field specification.
• Roles: created at runtime via the API or Studio. Group permission keys together (e.g. an admin role with all keys, a viewer role with only .read keys). Roles support inheritance — a role can inherit permission keys from other roles, forming a hierarchy.
• Assignments: map a user to one or more roles.
• Inheritance: roles can declare an inherits list pointing to other roles. The system walks the full inheritance chain and merges all permission keys transitively. Cycles are detected and rejected.

Actions

Each permission key maps to an HTTP method on the Data API:

To gate custom actions, declare matching keys in the permissions block (e.g. action.pipeline).

Using Studio

Use the Roles & Permissions panel in Studio to create roles, attach permission keys, and assign roles to users. Changes take effect immediately on the user's next request.

Using Code

Assign a role

POST /api/v1/apps/{appId}/roles/assign
{ "userId": "3f7a1b2c-...", "role": "manager" }

Takes effect immediately on the user's next request.

Revoke a role

POST /api/v1/apps/{appId}/roles/revoke
{ "userId": "3f7a1b2c-...", "role": "manager" }

List assignments

GET /api/v1/apps/{appId}/roles/assignments

Query effective permissions

GET /api/v1/apps/{appId}/permissions/{userId}

Returns the fully resolved permission set for the user:

{
  "roles": ["member"],
  "permissions": ["contacts.create", "contacts.read", "contacts.update", "deals.read"]
}