Roles
Roles define the permissions and privileges that a user or team receives within an organization. Assigning a role grants a consistent set of access rights across a domain, such as the organization, the CMS, or Asset Manager. Every endpoint below enforces an organization-level permission check, so a caller without the required access receives a 403 Forbidden response.
NoteBefore executing any calls, retrieve the authtoken by authenticating yourself via the Log in call of User Session. The authtoken is returned in the 'Response' body of the Log in call and is mandatory in all of the calls.
Get all roles
https://api.contentstack.io/v4/organizations/{organization_uid}/rolesThe Get all roles request returns all roles defined in your organization, so you can review the permissions and privileges granted within each domain.
Contentstack takes the organization from the organization_uid path parameter and enforces an organization-level permission check; a caller without the required access receives a 403 response. By default, the response is a flat roles array. Add include_count to return a count, and use skip, limit, asc, desc, and typeahead to page, sort, and search the results.
Filter the results by domain with domain, and enrich each role with include_user_details, include_stack_roles, or include_privilege_permissions. Set group_by_domain to “true” to receive a domain-keyed object instead of the flat list.
{
"roles": [
{
"_id": "665ff127a2dc68f3c31d96c4",
"name": "access_manager",
"uid": "blt**************rl",
"description": "Access Manager role.",
"org_uid": "blt**************b5",
"domain": "organization",
"default": false,
"permissions": ["org.info:read", "org.users:read", "org.users:write"],
"privileges": ["blt**************p1"],
"global_permissions": [],
"required_roles": null,
"can_invite": true,
"admin": false,
"owner_uid": "blt**************f0",
"tags": [],
"created_at": "2024-06-05T05:01:27.165Z",
"updated_at": "2024-06-05T05:01:27.165Z",
"deleted_at": false,
"created_by": "blt**************f0",
"updated_by": "blt**************f0",
"__v": 0
}
],
"count": 20
}Get a single role
https://api.contentstack.io/v4/organizations/{organization_uid}/roles/{role_uid}The Get a single role request returns the full definition of one role in your organization, including its permissions, privileges, domain, and assignment metadata.
Pass the organization UID as organization_uid and the role UID as role_uid in the request path. The endpoint enforces an organization-level permission check; a caller without the required access receives a 403 response.
{
"role": {
"_id": "665ff127a2dc68f3c31d96c4",
"name": "access_manager",
"uid": "blt**************rl",
"description": "Access Manager role.",
"org_uid": "blt**************b5",
"domain": "organization",
"default": false,
"permissions": ["org.info:read", "org.users:read", "org.users:write"],
"privileges": ["blt**************p1"],
"global_permissions": [],
"required_roles": null,
"can_invite": true,
"admin": false,
"owner_uid": "blt**************f0",
"tags": [],
"created_at": "2024-06-05T05:01:27.165Z",
"updated_at": "2024-06-05T05:01:27.165Z",
"deleted_at": false,
"created_by": "blt**************f0",
"updated_by": "blt**************f0",
"__v": 0
}
}Create a role
https://api.contentstack.io/v4/organizations/{organization_uid}/rolesThe Create a role request creates a role in the specified organization and grants it a set of permissions or privileges within a domain.
Provide the role name, a description, and the domain the role belongs to. Supply either a permissions array or a privileges array (at least one is required, and each must contain a minimum of one entry). You can optionally assign users at creation through a users array.
A role in the organization domain must include org.info:read in its permissions. On success, the request returns a 201 response with the created role. A duplicate name returns 409, and invalid permissions or users return 400.
{
"name": "config_admin",
"description": "The role allows a user to manage app config.",
"domain": "developerhub",
"permissions": [
"developerhub.config:write",
"developerhub.config:read"
],
"users": [
"blt**************a0"
]
}{
"role": {
"_id": "665ff127a2dc68f3c31d96c4",
"name": "access_manager",
"uid": "blt**************rl",
"description": "Access Manager role.",
"org_uid": "blt**************b5",
"domain": "organization",
"default": false,
"permissions": ["org.info:read", "org.users:read", "org.users:write"],
"privileges": ["blt**************p1"],
"global_permissions": [],
"required_roles": null,
"can_invite": true,
"admin": false,
"owner_uid": "blt**************f0",
"tags": [],
"created_at": "2024-06-05T05:01:27.165Z",
"updated_at": "2024-06-05T05:01:27.165Z",
"deleted_at": false,
"created_by": "blt**************f0",
"updated_by": "blt**************f0",
"__v": 0
}
}Update a role
https://api.contentstack.io/v4/organizations/{organization_uid}/roles/{role_uid}The Update a role request modifies an existing role in your organization. All fields are optional except domain, and you must send at least one field to change.
The permissions you send replace the role’s existing permissions, so include every permission you want the role to retain. A role in the organization domain must retain org.info:read.
You cannot change role membership through this request. Sending a users field returns a 400 response with the error code role.ROLE_USERS_NOT_PATCHABLE. To assign a role to users, invite or share them into the organization with that role through the Add users or Update user permissions request, assign the role to a team, or pass a users array when you create the role.
Default roles, such as Admin and Member, cannot be updated and return a 400 response with the error code DefaultRoleUpdateError. On success, the request returns a 200 response with the updated role, and the change applies to every user who holds it.
{
"name": "admin",
"description": "Access Manager role.",
"domain": "organization",
"permissions": [
"org.info:read",
"org.analytics:read"
]
}{
"role": {
"_id": "665ff127a2dc68f3c31d96c4",
"name": "access_manager",
"uid": "blt**************rl",
"description": "Access Manager role.",
"org_uid": "blt**************b5",
"domain": "organization",
"default": false,
"permissions": ["org.info:read", "org.users:read", "org.users:write"],
"privileges": ["blt**************p1"],
"global_permissions": [],
"required_roles": null,
"can_invite": true,
"admin": false,
"owner_uid": "blt**************f0",
"tags": [],
"created_at": "2024-06-05T05:01:27.165Z",
"updated_at": "2024-06-05T05:01:27.165Z",
"deleted_at": false,
"created_by": "blt**************f0",
"updated_by": "blt**************f0",
"__v": 0
}
}Delete roles
https://api.contentstack.io/v4/organizations/{organization_uid}/rolesThe Delete roles request removes one or more roles from your organization in a single call. Pass the role UIDs to delete in a role_uids array in the request body.
Deleting a role removes it from the org_roles of every user who had it. A user left with no organization roles is automatically assigned the built-in Member role, and references to the deleted roles in team assignments are cleaned up. Roles are soft-deleted rather than removed permanently, and the permissions of all affected users are re-synced.
{
"role_uids": [
"blt**************r1",
"blt**************r2"
]
}{
"deleted": true
}Get role permissions
https://api.contentstack.io/v4/organizations/{organization_uid}/roles/{role_uid}/permissionsThe Get role permissions request returns the permissions currently assigned to a role, so you can review its access without fetching the full role object.
Pass the organization UID as organization_uid and the role UID as role_uid in the request path. This endpoint requires the caller to hold the data.organization.roles.write permission, not read.
{
"permissions": [
"org.info:read",
"org.users:read"
]
}Update role permissions
https://api.contentstack.io/v4/organizations/{organization_uid}/roles/{role_uid}/permissionsThe Update role permissions request replaces the permission set of a role with the permissions you send. Include every permission the role should hold, because the request replaces rather than merges.
Send at least one permission. A role in the organization domain must retain org.info:read. On success, the request returns a 200 response with the full updated role.
{
"permissions": [
"org.info:read"
]
}{
"role": {
"_id": "665ff127a2dc68f3c31d96c4",
"name": "access_manager",
"uid": "blt**************rl",
"description": "Access Manager role.",
"org_uid": "blt**************b5",
"domain": "organization",
"default": false,
"permissions": ["org.info:read", "org.users:read", "org.users:write"],
"privileges": ["blt**************p1"],
"global_permissions": [],
"required_roles": null,
"can_invite": true,
"admin": false,
"owner_uid": "blt**************f0",
"tags": [],
"created_at": "2024-06-05T05:01:27.165Z",
"updated_at": "2024-06-05T05:01:27.165Z",
"deleted_at": false,
"created_by": "blt**************f0",
"updated_by": "blt**************f0",
"__v": 0
}
}Get role users
https://api.contentstack.io/v4/organizations/{organization_uid}/roles/{role_uid}/usersThe Get role users request returns the users assigned to a role in your organization.
Pass the organization UID as organization_uid and the role UID as role_uid in the request path.
This request is read-only for role membership, and there is no request that adds or removes a single user from a role. To change who holds a role, invite or share users into the organization with that role through the Add users or Update user permissions request, assign the role to a team, or pass a users array when you create the role. The Update a role request rejects a users field.
[
{
"uid": "blt**************a0",
"first_name": "John",
"last_name": "Doe",
"email": "[email protected]"
}
]