Role
A role is a named grant of access inside one organization, holding a set of capabilities and a set of permissions.
A role belongs to exactly one organization and is prefixed ROL_. An
organization owner assigns it to the memberships of one or
more users, and every user it names gains what it grants inside that
organization. Its capabilities grant organization-wide
administrative powers. Its permissions grant access levels over
specific Spaces, resource groups, and
other roles. A user's access is the union of what all their assigned roles
grant, and on any single target the highest level any of those roles grants is
the one that applies. A membership with no role gains nothing.
Capabilities
A capability is an organization-wide administrative grant, carrying no Space or
resource scope. A role's capabilities array holds any of these five values.
| Value | Description |
|---|---|
ManageGeneralSettings | Manage the organization's general settings. |
ManageCasesSettings | Manage case workflow settings, such as severities, phases, and types. |
ManageSso | Manage single sign-on for the organization. |
ManageDataPlane | Manage the organization's data plane. |
ManageSimbaSettings | Manage settings for the Simba agent. |
Permissions
A permission grants one access level over one target resource. A role's
permissions array holds any number of these entries, each with a resourceId
and an access.
| Field | Type | Required | Description |
|---|---|---|---|
resourceId | string | Required | The target the access applies to. A Space (SPC_), a resource group (RGP_), or another role (ROL_). |
access | enum | Required | The access level granted. See the levels below. |
The three access levels are ordered from least to most permissive, and a grant
carries every level beneath it. A grant of execute therefore satisfies a
check for write or read. Which levels a target accepts depends on the target
kind.
| Value | Description |
|---|---|
read | View content and datasets on the target, and query the datasets. |
write | Edit content on the target. |
execute | Invoke the HTTP Tools and MCP Servers configured on the target. |
A Space or a resource group target
accepts all three levels. A role target accepts only read and write, which
grant the ability to view and to manage that role. These three levels also
appear on a Space's own permissions field, which is the same binding from the
Space's side.
Resource groups
A resource group is an organization-level collection of resources that a
permission can target to grant access across a whole class at once. Each
organization has a fixed group hierarchy: an Organization root containing
Content Packs, Roles, and Spaces. A permission on the Spaces group, for
example, grants its access level across every Space in the organization. A
resource group is prefixed RGP_.
Inputs
The fields a caller provides on create or update.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Required | Role name. |
description | string | Optional | Free-text description of the role. |
capabilities | array<enum> | Required | Organization-wide administrative grants. See capabilities. |
permissions | array<object> | Required | Access-level grants over specific resources. Each entry has resourceId and access. See permissions. |
userIds | array<string> | Required | The users to assign this role to, each prefixed USR_. |
Outputs
The full shape the API returns.
| Field | Type | Description |
|---|---|---|
parentId | string | Always null. Roles have no parent role. |
Plus the common resource fields.
Related
- Users. An organization owner assigns a role to a user's membership.
- Organizations. The tenant a role belongs to.
- Spaces. The access-controlled namespaces a permission targets.