Member Roles

Tags: members, permissions, roles

Member role and permission management

In the product: Roles

Resources

Request and response models used by the endpoints on this page.

CreateMemberRoleRequest

Field	Type	Required	Description
calendarAccess	Array<dict[str, int]>
dataTypeAccess	Array<dict[str, int]>
fileAccess	Array<dict[str, int]>
folderAccess	Array<dict[str, int]>
grantedScopes	Array
inboxAccess	Array<dict[str, int]>
name	String	✓
siteAccess	Array<dict[str, int]>
workflowAccess	Array<dict[str, int]>

Example:

{
  "name": "string"  // String,
  "grantedScopes": "string"  // Array<String>, optional,
  "siteAccess": {}  // Array<dict[str, int]>, optional,
  "dataTypeAccess": {}  // Array<dict[str, int]>, optional,
  "workflowAccess": {}  // Array<dict[str, int]>, optional,
  "inboxAccess": {}  // Array<dict[str, int]>, optional,
  "fileAccess": {}  // Array<dict[str, int]>, optional,
  "folderAccess": {}  // Array<dict[str, int]>, optional,
  "calendarAccess": {}  // Array<dict[str, int]>, optional
}

DriftedSystemRoleResponse

Field	Type	Required	Description
canonicalName	String	✓
extraScopes	Array		Default: []
missingScopes	Array		Default: []
name	String	✓
nameMatches	Boolean	✓
roleId	Integer	✓
systemKey	String	✓

Example:

{
  "roleId": 0  // Integer,
  "name": "string"  // String,
  "systemKey": "string"  // String,
  "canonicalName": "string"  // String,
  "nameMatches": false  // Boolean,
  "missingScopes": "string"  // Array<String>, optional, default: [],
  "extraScopes": "string"  // Array<String>, optional, default: []
}

LegacyRoleSuggestionResponse

Field	Type	Required	Description
matchType	String	✓	How confident the match is. 'duplicate_name' — the role folds to the same canonical name as the target, so it is unambiguously the same role written differently; safe to merge. 'legacy_alias' — an older name for the target (e.g. 'admin' for Manager); this is a guess, the role may have been customised into something the workspace relies on, so clients should require explicit review rather than pre-selecting it.
references	RoleReferenceCountsResponse	✓	Counts of everything in the workspace that points at the source role and would move.
resourcesTargetWouldGain	Integer		Resources the source role can reach that the target cannot. Under the 'union' access strategy these become newly reachable for everyone who already holds the target role. (default: 0)
sourceRoleId	Integer	✓
sourceRoleName	String	✓
systemKey	String	✓
targetRoleId	Integer	✓
targetRoleName	String	✓

Example:

{
  "sourceRoleId": 0  // Integer,
  "sourceRoleName": "string"  // String,
  "targetRoleId": 0  // Integer,
  "targetRoleName": "string"  // String,
  "systemKey": "string"  // String,
  "matchType": "string"  // String, How confident the match is. 'duplicate_name' — the role folds to the same canonical name as the target, so it is unambiguously the same role written differently; safe to merge. 'legacy_alias' — an older name for the target (e.g. 'admin' for Manager); this is a guess, the role may have been customised into something the workspace relies on, so clients should require explicit review rather than pre-selecting it.,
  "references": null  // RoleReferenceCountsResponse, Counts of everything in the workspace that points at the source role and would move.,
  "resourcesTargetWouldGain": 0  // Integer, optional, default: 0, Resources the source role can reach that the target cannot. Under the 'union' access strategy these become newly reachable for everyone who already holds the target role.
}

MemberRoleCalendarAccessResponse

Field	Type	Required	Description
accessMode	Integer	✓
calendarId	Integer	✓

Example:

{
  "calendarId": 0  // Integer,
  "accessMode": 0  // Integer
}

MemberRoleCleanupPlanResponse

Field	Type	Required	Description
drifted	Array		Default: []
isClean	Boolean		Default: True
missingSystemKeys	Array		Default: []
suggestions	Array		Default: []

Example:

{
  "suggestions": []  // Array<LegacyRoleSuggestionResponse>, optional, default: [],
  "drifted": []  // Array<DriftedSystemRoleResponse>, optional, default: [],
  "missingSystemKeys": "string"  // Array<String>, optional, default: [],
  "isClean": false  // Boolean, optional, default: True
}

MemberRoleDataTypeAccessResponse

Field	Type	Required	Description
accessMode	Integer	✓
dataTypeId	Integer	✓

Example:

{
  "dataTypeId": 0  // Integer,
  "accessMode": 0  // Integer
}

MemberRoleFileAccessResponse

Field	Type	Required	Description
accessMode	Integer	✓
fileId	Integer	✓

Example:

{
  "fileId": 0  // Integer,
  "accessMode": 0  // Integer
}

MemberRoleFolderAccessResponse

Field	Type	Required	Description
accessMode	Integer	✓
folderId	Integer	✓

Example:

{
  "folderId": 0  // Integer,
  "accessMode": 0  // Integer
}

MemberRoleInboxAccessResponse

Field	Type	Required	Description
accessMode	Integer	✓
inboxId	Integer	✓

Example:

{
  "inboxId": 0  // Integer,
  "accessMode": 0  // Integer
}

MemberRoleResponse

Field	Type	Required	Description
calendarAccess	Array		Default: []
createdAt	DateTime	✓
dataTypeAccess	Array		Default: []
fileAccess	Array		Default: []
folderAccess	Array		Default: []
grantedScopes	Array		Default: []
id	Integer	✓
inboxAccess	Array		Default: []
isDefaultForNewMembers	Boolean		Default: False
memberCount	Integer		Default: 0
name	String	✓
siteAccess	Array		Default: []
systemKey	String
updatedAt	DateTime	✓
uuid	String	✓
workflowAccess	Array		Default: []

Example:

{
  "id": 0  // Integer,
  "uuid": "string"  // String,
  "name": "string"  // String,
  "systemKey": "string"  // String, optional,
  "grantedScopes": "string"  // Array<String>, optional, default: [],
  "siteAccess": []  // Array<MemberRoleSiteAccessResponse>, optional, default: [],
  "dataTypeAccess": []  // Array<MemberRoleDataTypeAccessResponse>, optional, default: [],
  "workflowAccess": []  // Array<MemberRoleWorkflowAccessResponse>, optional, default: [],
  "inboxAccess": []  // Array<MemberRoleInboxAccessResponse>, optional, default: [],
  "fileAccess": []  // Array<MemberRoleFileAccessResponse>, optional, default: [],
  "folderAccess": []  // Array<MemberRoleFolderAccessResponse>, optional, default: [],
  "calendarAccess": []  // Array<MemberRoleCalendarAccessResponse>, optional, default: [],
  "memberCount": 0  // Integer, optional, default: 0,
  "isDefaultForNewMembers": false  // Boolean, optional, default: False,
  "createdAt": "2024-01-01T00:00:00Z"  // DateTime,
  "updatedAt": "2024-01-01T00:00:00Z"  // DateTime
}

MemberRoleSiteAccessResponse

Field	Type	Required	Description
accessMode	Integer	✓
siteId	Integer	✓

Example:

{
  "siteId": 0  // Integer,
  "accessMode": 0  // Integer
}

MemberRoleWorkflowAccessResponse

Field	Type	Required	Description
accessMode	Integer	✓
workflowId	Integer	✓

Example:

{
  "workflowId": 0  // Integer,
  "accessMode": 0  // Integer
}

MergeMemberRolesRequest

Field	Type	Required	Description
accessStrategy	Literal[union, target_only]		Default: union
sourceRoleId	Integer	✓
targetRoleId	Integer	✓

Example:

{
  "sourceRoleId": 0  // Integer,
  "targetRoleId": 0  // Integer,
  "accessStrategy": null  // Literal[union, target_only], optional, default: union
}

MergeMemberRolesResponse

Field	Type	Required	Description
accessRowsDiscarded	Integer		Default: 0
accessRowsMerged	Integer		Default: 0
accessRowsMoved	Integer		Default: 0
anonymousPhoneNumbersMoved	Integer		Default: 0
invitationsMoved	Integer		Default: 0
membersMoved	Integer		Default: 0
personasMoved	Integer		Default: 0
signupPhoneNumbersMoved	Integer		Default: 0
signupSitesMoved	Integer		Default: 0
sourceRoleId	Integer	✓
sourceRoleName	String	✓
strategy	String	✓
targetRoleId	Integer	✓
targetRoleName	String	✓

Example:

{
  "sourceRoleId": 0  // Integer,
  "sourceRoleName": "string"  // String,
  "targetRoleId": 0  // Integer,
  "targetRoleName": "string"  // String,
  "strategy": "string"  // String,
  "membersMoved": 0  // Integer, optional, default: 0,
  "accessRowsMoved": 0  // Integer, optional, default: 0,
  "accessRowsMerged": 0  // Integer, optional, default: 0,
  "accessRowsDiscarded": 0  // Integer, optional, default: 0,
  "signupSitesMoved": 0  // Integer, optional, default: 0,
  "signupPhoneNumbersMoved": 0  // Integer, optional, default: 0,
  "anonymousPhoneNumbersMoved": 0  // Integer, optional, default: 0,
  "personasMoved": 0  // Integer, optional, default: 0,
  "invitationsMoved": 0  // Integer, optional, default: 0
}

RoleReferenceCountsResponse

Field	Type	Required	Description
anonymousPhoneNumbers	Integer		Phone numbers that assign this role to anonymous callers. (default: 0)
members	Integer		Members holding the role. (default: 0)
pendingInvitations	Integer		Invitations not yet accepted or declined that would grant this role. (default: 0)
personas	Integer		Agent personas that instantiate with this role. (default: 0)
resourceAccess	Integer		Resource-access grants across all association families (sites, forms, workflows, inboxes, files, folders, calendars, calendar event types). (default: 0)
signupPhoneNumbers	Integer		Phone numbers that assign this role on signup. (default: 0)
signupSites	Integer		Sites that assign this role on signup. (default: 0)
total	Integer		Sum of every count above. (default: 0)

Example:

{
  "members": 0  // Integer, optional, default: 0, Members holding the role.,
  "resourceAccess": 0  // Integer, optional, default: 0, Resource-access grants across all association families (sites, forms, workflows, inboxes, files, folders, calendars, calendar event types).,
  "signupSites": 0  // Integer, optional, default: 0, Sites that assign this role on signup.,
  "signupPhoneNumbers": 0  // Integer, optional, default: 0, Phone numbers that assign this role on signup.,
  "anonymousPhoneNumbers": 0  // Integer, optional, default: 0, Phone numbers that assign this role to anonymous callers.,
  "personas": 0  // Integer, optional, default: 0, Agent personas that instantiate with this role.,
  "pendingInvitations": 0  // Integer, optional, default: 0, Invitations not yet accepted or declined that would grant this role.,
  "total": 0  // Integer, optional, default: 0, Sum of every count above.
}

UpdateMemberRoleRequest

Field	Type	Required	Description
calendarAccess	Array<dict[str, int]>
dataTypeAccess	Array<dict[str, int]>
fileAccess	Array<dict[str, int]>
folderAccess	Array<dict[str, int]>
grantedScopes	Array
inboxAccess	Array<dict[str, int]>
name	String
siteAccess	Array<dict[str, int]>
workflowAccess	Array<dict[str, int]>

Example:

{
  "name": "string"  // String, optional,
  "grantedScopes": "string"  // Array<String>, optional,
  "siteAccess": {}  // Array<dict[str, int]>, optional,
  "dataTypeAccess": {}  // Array<dict[str, int]>, optional,
  "workflowAccess": {}  // Array<dict[str, int]>, optional,
  "inboxAccess": {}  // Array<dict[str, int]>, optional,
  "fileAccess": {}  // Array<dict[str, int]>, optional,
  "folderAccess": {}  // Array<dict[str, int]>, optional,
  "calendarAccess": {}  // Array<dict[str, int]>, optional
}

Endpoints

• GET /api/v2/w/{workspace_uuid}/member-roles - List
• POST /api/v2/w/{workspace_uuid}/member-roles - Create
• GET /api/v2/w/{workspace_uuid}/member-roles/cleanup-plan - Cleanup Plan
• POST /api/v2/w/{workspace_uuid}/member-roles/cleanup/merge - Merge
• GET /api/v2/w/{workspace_uuid}/member-roles/{role_id_or_uuid} - Get Role Id Or Uuid
• DELETE /api/v2/w/{workspace_uuid}/member-roles/{role_id} - Delete Role Id
• PUT /api/v2/w/{workspace_uuid}/member-roles/{role_id} - Update Role Id

List

GET /api/v2/w/{workspace_uuid}/member-roles

Description:

List all member roles.

Authorization: Requires member-roles:read scope

Response: List of MemberRoleResponse

---

Create

POST /api/v2/w/{workspace_uuid}/member-roles

Description:

Create a new member role.

Always creates a custom role. Returns 400 if the name is already taken, or if it matches one of the platform's default role names (case- and punctuation-insensitively) — those names are reserved.

Authorization: Requires member-roles:admin scope

Parameters:

• request - See CreateMemberRoleRequest

Response: See MemberRoleResponse

---

Cleanup Plan

GET /api/v2/w/{workspace_uuid}/member-roles/cleanup-plan

Description:

Describe the workspace's legacy default-role duplicates. Changes nothing.

Reports duplicates of the platform's default roles left behind by older versions of the product, how many members and references each would move, and any default role whose name or permissions have drifted.

Authorization: Requires member-roles:admin scope

Response: See MemberRoleCleanupPlanResponse

---

Merge

POST /api/v2/w/{workspace_uuid}/member-roles/cleanup/merge

Description:

Move every member and reference from one role to another, then delete it.

accessStrategy controls the source role's resource access: union (default) copies it onto the target, so nobody who held the source loses access; target_only discards it, so nothing is widened for people who already held the target. Irreversible.

Returns 404 if either role does not exist, and 400 if the two are the same role or the source is one of the platform's default roles — those are never deleted.

Authorization: Requires member-roles:admin scope

Parameters:

• request - See MergeMemberRolesRequest

Response: See MergeMemberRolesResponse

---

Get Role Id Or Uuid

GET /api/v2/w/{workspace_uuid}/member-roles/{role_id_or_uuid}

Description:

Get a specific member role by ID or UUID. Users can view their own role, managers can view any role.

Authorization: Requires member-roles:read scope

Parameters:

• role_id_or_uuid (String)

Response: See MemberRoleResponse

---

Delete Role Id

DELETE /api/v2/w/{workspace_uuid}/member-roles/{role_id}

Description:

Delete a member role.

Returns 403 for one of the platform's default roles, 400 if any members are still assigned to the role, and 404 if it does not exist.

Authorization: Requires member-roles:admin scope

Parameters:

• role_id (Integer)

Response: See None

---

Update Role Id

PUT /api/v2/w/{workspace_uuid}/member-roles/{role_id}

Description:

Update an existing member role.

Returns 403 when the role is one of the platform's default roles and the request changes its name or granted scopes; those are fixed. Resource access remains editable on every role. Returns 404 if the role does not exist, and 400 if the new name is already taken.

Authorization: Requires member-roles:admin scope

Parameters:

• role_id (Integer)
• request - See UpdateMemberRoleRequest

Response: See MemberRoleResponse

---