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
dailyCreditLimit	Integer
fileAccess	Array<dict[str, int]>
folderAccess	Array<dict[str, int]>
grantedScopes	Array
name	String	✓
siteAudience	Array

Example:

{
  "name": "string"
}

DriftedSystemRoleResponse

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

Example:

{
  "roleId": 0,
  "name": "string",
  "systemKey": "string",
  "canonicalName": "string",
  "nameMatches": false,
  "missingScopes": [],
  "extraScopes": []
}

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,
  "sourceRoleName": "string",
  "targetRoleId": 0,
  "targetRoleName": "string",
  "systemKey": "string",
  "matchType": "string",
  "references": null,
  "resourcesTargetWouldGain": 0
}

MemberRoleCleanupPlanResponse

Field	Type	Required	Description
drifted	Array<DriftedSystemRoleResponse>		Default: []
isClean	Boolean		Default: True
missingSystemKeys	Array		Default: []
suggestions	Array<LegacyRoleSuggestionResponse>		Default: []

Example:

{
  "suggestions": [],
  "drifted": [],
  "missingSystemKeys": [],
  "isClean": true
}

MemberRoleFileAccessResponse

Field	Type	Required	Description
accessMode	Integer	✓
fileId	Integer	✓

Example:

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

MemberRoleFolderAccessResponse

Field	Type	Required	Description
accessMode	Integer	✓
folderId	Integer	✓

Example:

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

MemberRoleResponse

Field	Type	Required	Description
createdAt	DateTime	✓
dailyCreditLimit	Integer
fileAccess	Array<MemberRoleFileAccessResponse>		Default: []
folderAccess	Array<MemberRoleFolderAccessResponse>		Default: []
grantedScopes	Array		Default: []
id	Integer	✓
isDefaultForNewMembers	Boolean		Default: False
memberCount	Integer		Default: 0
name	String	✓
siteAudience	Array		Default: []
systemKey	String
updatedAt	DateTime	✓
uuid	String	✓

Example:

{
  "id": 0,
  "uuid": "string",
  "name": "string",
  "grantedScopes": [],
  "siteAudience": [],
  "fileAccess": [],
  "folderAccess": [],
  "memberCount": 0,
  "isDefaultForNewMembers": false,
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-01T00:00:00Z"
}

MergeMemberRolesRequest

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

Example:

{
  "sourceRoleId": 0,
  "targetRoleId": 0,
  "accessStrategy": "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
memberSubscriptionsMoved	Integer		Default: 0
membersMoved	Integer		Default: 0
personasMoved	Integer		Default: 0
productsMoved	Integer		Default: 0
signupPhoneNumbersMoved	Integer		Default: 0
signupRoutingRulesMoved	Integer		Default: 0
signupSitesMoved	Integer		Default: 0
sourceRoleId	Integer	✓
sourceRoleName	String	✓
strategy	String	✓
targetRoleId	Integer	✓
targetRoleName	String	✓

Example:

{
  "sourceRoleId": 0,
  "sourceRoleName": "string",
  "targetRoleId": 0,
  "targetRoleName": "string",
  "strategy": "string",
  "membersMoved": 0,
  "accessRowsMoved": 0,
  "accessRowsMerged": 0,
  "accessRowsDiscarded": 0,
  "signupSitesMoved": 0,
  "signupPhoneNumbersMoved": 0,
  "signupRoutingRulesMoved": 0,
  "anonymousPhoneNumbersMoved": 0,
  "personasMoved": 0,
  "invitationsMoved": 0,
  "productsMoved": 0,
  "memberSubscriptionsMoved": 0
}

RoleReferenceCountsResponse

Field	Type	Required	Description
anonymousPhoneNumbers	Integer		Phone numbers whose stored anonymous role names this role. The column is not read at runtime; routing rules name the role for new callers. (default: 0)
memberSubscriptions	Integer		Paid member subscriptions whose granted or previous role points at this role. (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)
products	Integer		MEMBER products whose checkout grants this role. (default: 0)
resourceAccess	Integer		Site audience, File access and Folder access rows naming the role. (default: 0)
signupPhoneNumbers	Integer		Phone numbers that assign this role on signup. (default: 0)
signupRoutingRules	Integer		Routing Rules that give this role to new callers. (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,
  "resourceAccess": 0,
  "signupSites": 0,
  "signupPhoneNumbers": 0,
  "signupRoutingRules": 0,
  "anonymousPhoneNumbers": 0,
  "personas": 0,
  "pendingInvitations": 0,
  "products": 0,
  "memberSubscriptions": 0,
  "total": 0
}

UpdateMemberRoleRequest

Field	Type	Required	Description
dailyCreditLimit	Integer
fileAccess	Array<dict[str, int]>
folderAccess	Array<dict[str, int]>
grantedScopes	Array
name	String
siteAudience	Array

Example:

{}

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, the source is a platform default (those are never deleted), or an accountless human would be moved into built-in Manager/User.

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 or any still-claimable invitation names it, and 404 if it does not exist.

Authorization: Requires member-roles:admin scope

Parameters:

• role_id (Integer)

Response: 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. Site audience and File/Folder access remain 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

---