GetRoleRequest
| Field | Type |
|---|---|
id | string |
Get, Create, and Update Roles
All operations use POST /public-api/publicapi.v1.Role/. Role read/write
authorization and exact API scopes both apply.
Get uses role:read, create role:create, and update role:update.
Roles and Customer Views
Section titled “Roles and Customer Views”These contracts expose administrative grants, not effective operational or
customer access. Operational capabilities normally come from matching Customer
Views; customer ACL remains authoritative. Roles can select Views, but creating
or updating a role does not configure a View. The owning authorization model’s
exception is board FULL_ACCESS, which also enables all operational capabilities.
Do not grant it merely to make an integration’s operation available.
Supported access fields are teamAccess, boardAccess, memberAccess,
roleAccess, settingsAccess, securityAccess, auditAccess, billingAccess,
developmentAccess, inventoryAccess, planningAccess, agentChatAccess, and
workflowAutomationAccess. Each supplied field
needs an explicit level: PUBLIC_DIRECTORY_PERMISSION_LEVEL_NONE,
PUBLIC_DIRECTORY_PERMISSION_LEVEL_READ_ONLY,
PUBLIC_DIRECTORY_PERMISSION_LEVEL_READ_WRITE, or
PUBLIC_DIRECTORY_PERMISSION_LEVEL_FULL_ACCESS.
Optional delegateUpTo uses the same enum, defaults to no delegation, and
cannot exceed the grant or the actor’s delegation ceiling. Omitted access fields
mean NONE, not inherited defaults. Never send internal permission numbers or
legacy permission strings.
agentChatAccess at READ_WRITE enables private interactive chat; it does not
grant resource or tool access. Omission grants no chat access or delegation.
workflowAutomationAccess controls workflow authoring independently of Settings,
Board, Customer Views, operational automation, and interactive chat. Its nested
allowAiAgents flag requires at least READ_WRITE. Its delegateAiAgents flag
requires allowAiAgents and at least READ_WRITE in delegateUpTo. Both flags
default to false. Granting either flag requires the actor’s delegateAiAgents;
role-management or Settings access alone cannot grant workflow AI authority.
GetRole
Section titled “GetRole”{ "id": "<role-id>" }Returns role metadata and a separate access object. Reading a role does not
authorize assigning or delegating it.
Generated Reference
POST /public-api/publicapi.v1.Role/GetRole Gets administrative grants, not effective operational or customer access.
GetRoleResponse
| Field | Type |
|---|---|
role | Role |
access | DirectoryRoleAccess |
CreateRole
Section titled “CreateRole”{ "name": "Inventory reader", "description": "Read stock records", "access": { "inventoryAccess": { "level": "PUBLIC_DIRECTORY_PERMISSION_LEVEL_READ_ONLY" } }, "isDefault": false, "requires2fa": true}Creates a custom role. Name must be nonblank, maximum 50 characters; description
maximum 1,000. Omitted access grants no administrative permissions. Creation
does not assign the role to a member. Returns role and access.
Generated Reference
POST /public-api/publicapi.v1.Role/CreateRole Creates a custom role. Omitted access grants no administrative permissions. Roles can also select Customer Views; this does not configure those Views. Not idempotent.
CreateRoleRequest
| Field | Type |
|---|---|
name | string |
description | string |
access | DirectoryRoleAccess |
is_default | bool |
requires_2fa | bool |
CreateRoleResponse
| Field | Type |
|---|---|
role | Role |
access | DirectoryRoleAccess |
UpdateRole
Section titled “UpdateRole”Supply id, a nonblank name, the complete desired access, and desired flags.
This replaces administrative grants, not a partial access patch. access: {}
removes every administrative grant; omitted access is invalid. False or omitted
isDefault/requires2fa clears that flag. Empty description preserves the
existing description, rather than clearing it.
System and owner roles cannot be updated through this operation. Both existing and requested grants must fit the creator’s delegation ceiling. Member role replacement separately preserves the last workspace owner. Create/update are not idempotent; inspect current state before retrying a timeout.
Generated Reference
POST /public-api/publicapi.v1.Role/UpdateRole Replaces custom role access and flags. Access must be explicit; {} removes all administrative grants. Empty description preserves the existing value. System and owner roles cannot be updated through this public operation. Not idempotent; existing and requested grants must fit the delegation ceiling.
UpdateRoleRequest
| Field | Type | Description |
|---|---|---|
id | string | |
name | string | |
description | string | |
access | DirectoryRoleAccess | |
is_default | bool | Explicit desired flags; false clears the flag. |
requires_2fa | bool |
UpdateRoleResponse
| Field | Type |
|---|---|
role | Role |
access | DirectoryRoleAccess |