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.
Note: Before 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.
" url: "https://www.contentstack.com/docs/developers/apis/administration-api/roles" product: "Contentstack" doc_type: "guide" audience: - developers - admins version: "current" last_updated: "2026-07-16" --- # Administration | 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. **Note**: Before 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 ### Get all roles **GET** `/v4/organizations/{organization_uid}/roles` The 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. #### URL Parameters - **organization_uid** (required) Enter the UID of your Organization. #### Query Parameters - **include_count** (optional) Set this parameter to “true” to include the total count of roles in the response. - **group_by_domain** (optional) Set this parameter to “true” to group the roles by domain instead of returning a flat list. The cms domain returns stacks in place of roles. - **domain** (optional) Enter one or more domains in string format, separated by commas, to filter the roles. - **include_user_details** (optional) Set this parameter to “true” to include the users assigned to each role. - **include_stack_roles** (optional) Set this parameter to “true” to include CMS stack roles in the response. - **include_privilege_permissions** (optional) Set this parameter to “true” to add a permissionsFromPrivileges array to each role. - **skip** (optional) Enter the number of roles to skip from the response. - **limit** (optional) Enter the maximum number of roles to return. - **asc** (optional) Sort the response in ascending order by the given field name. - **desc** (optional) Sort the response in descending order by the given field name. - **typeahead** (optional) Retrieves roles whose name matches the provided string. #### Headers - **authtoken** (required) Enter your authtoken. Default: `your_authtoken` #### Sample Response ```json { "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 ### Get a single role **GET** `/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. #### URL Parameters - **organization_uid** (required) Enter the UID of your Organization. - **role_uid** (required) Enter the UID of the role. Execute the [Get all roles](/docs/developers/apis/administration-api#get-all-roles) request to retrieve the UID of a role. #### Headers - **authtoken** (required) Enter your authtoken. Default: `your_authtoken` #### Sample Response ```json { "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 ### Create a role **POST** `/v4/organizations/{organization_uid}/roles` The 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. #### URL Parameters - **organization_uid** (required) Enter the UID of your Organization. #### Headers - **authtoken** (required) Enter your authtoken. Default: `your_authtoken` - **Content-Type** (required) Enter "application/json" to pass a request body. Default: `application/json` #### Sample Response ```json { "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 ### Update a role **PATCH** `/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](/docs/developers/apis/administration-api#add-users) or [Update user permissions](/docs/developers/apis/administration-api#update-user-permissions) request, assign the role to a [team](/docs/administration/about-teams), 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. #### URL Parameters - **organization_uid** (required) Enter the UID of your Organization. - **role_uid** (required) Enter the UID of the role. Execute the [Get all roles](/docs/developers/apis/administration-api#get-all-roles) request to retrieve the UID of a role. #### Headers - **authtoken** (required) Enter your authtoken. Default: `your_authtoken` - **Content-Type** (required) Enter "application/json" to pass a request body. Default: `application/json` #### Sample Response ```json { "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 ### Delete roles **DELETE** `/v4/organizations/{organization_uid}/roles` The 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. #### URL Parameters - **organization_uid** (required) Enter the UID of your Organization. #### Headers - **authtoken** (required) Enter your authtoken. Default: `your_authtoken` - **Content-Type** (required) Enter "application/json" to pass a request body. Default: `application/json` #### Sample Response ```json { "deleted": true } ``` ## Get role permissions ### Get role permissions **GET** `/v4/organizations/{organization_uid}/roles/{role_uid}/permissions` The 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. #### URL Parameters - **organization_uid** (required) Enter the UID of your Organization. - **role_uid** (required) Enter the UID of the role. Execute the [Get all roles](/docs/developers/apis/administration-api#get-all-roles) request to retrieve the UID of a role. #### Query Parameters - **typeahead** (optional) Retrieves permissions that match the provided string. - **asc** (optional) Sort the response in ascending order by the given field name. - **desc** (optional) Sort the response in descending order by the given field name. #### Headers - **authtoken** (required) Enter your authtoken. Default: `your_authtoken` #### Sample Response ```json { "permissions": [ "org.info:read", "org.users:read" ] } ``` ## Update role permissions ### Update role permissions **PATCH** `/v4/organizations/{organization_uid}/roles/{role_uid}/permissions` The 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. #### URL Parameters - **organization_uid** (required) Enter the UID of your Organization. - **role_uid** (required) Enter the UID of the role. Execute the [Get all roles](/docs/developers/apis/administration-api#get-all-roles) request to retrieve the UID of a role. #### Headers - **authtoken** (required) Enter your authtoken. Default: `your_authtoken` - **Content-Type** (required) Enter "application/json" to pass a request body. Default: `application/json` #### Sample Response ```json { "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 ### Get role users **GET** `/v4/organizations/{organization_uid}/roles/{role_uid}/users` The 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](/docs/developers/apis/administration-api#add-users) or [Update user permissions](/docs/developers/apis/administration-api#update-user-permissions) request, assign the role to a [team](/docs/administration/about-teams), or pass a users array when you create the role. The [Update a role](/docs/developers/apis/administration-api#update-a-role) request rejects a users field. #### URL Parameters - **organization_uid** (required) Enter the UID of your Organization. - **role_uid** (required) Enter the UID of the role. Execute the [Get all roles](/docs/developers/apis/administration-api#get-all-roles) request to retrieve the UID of a role. #### Query Parameters - **skip** (optional) Enter the number of users to skip from the response. - **limit** (optional) Enter the maximum number of users to return. - **typeahead** (optional) Retrieves users whose name or email matches the provided string. - **asc** (optional) Sort the response in ascending order by the given field name. - **desc** (optional) Sort the response in descending order by the given field name. #### Headers - **authtoken** (required) Enter your authtoken. Default: `your_authtoken` #### Sample Response ```json [ { "uid": "blt**************a0", "first_name": "John", "last_name": "Doe", "email": "john.doe@contentstack.com" } ] ```