Roles
A role is a collection of permissions that will be applicable to all the users who are assigned with that role. Read more about Roles.
Get all roles
https://api.contentstack.io/v3/roles?include_permissions={boolean_value}&include_rules={boolean_value}The Get all roles request returns comprehensive information about all roles created in a stack.
You can add queries to extend the functionality of this API request. Under the URL Parameters section, insert a parameter named query and provide a query in JSON format as the value.
To learn more about the queries, refer to the Queries section of the Content Delivery API doc.
To configure the permissions for your application via OAuth, please include the cm.roles.management:read scope.
{
"roles":[
{
"name":"Developer",
"description":"Developer can perform all Content Manager's actions, view audit logs, create roles, invite users, manage content types, languages, and environments.",
"uid":"bltf177eec8730751a3",
"created_by":"blta7eaf6883dd73a0b",
"updated_by":"blta7eaf6883dd73a0b",
"created_at":"2021-09-16T11:54:15.300Z",
"updated_at":"2021-09-16T12:29:24.192Z",
"roles":[
],
"users":[
"blt1fd0057b90905592"
],
"owner":"[email protected]",
"stack":{
"created_at":"2021-09-16T11:54:14.172Z",
"updated_at":"2021-09-16T12:29:24.179Z",
"uid":"blt48b5e7f7b2f4b962",
"name":"My Site",
"description":"My site related content.",
"org_uid":"blteac54a27425b3b0e",
"api_key":"blt29ec365eaa0c8d67",
"master_locale":"en-us",
"is_asset_download_public":true,
"owner_uid":"blta7eaf6883dd73a0b",
"user_uids":[
"blta7eaf6883dd73a0b",
"blt1fd0057b90905592"
],
"settings":{
"version":"2019-04-30",
"rte_version":3,
"blockAuthQueryParams":true,
"allowedCDNTokens":[
"access_token"
],
"branches":true,
"webhook_enabled":true,
"stack_variables":{
},
"live_preview":{
},
"discrete_variables":{
"cms":true,
"_version":3,
"secret_key":"6ab0a6df0447b33386648f1d889d27b253ffe7fc"
},
"language_fallback":false,
"workflow_stages":true,
"publishing_rules":true
},
"master_key":"bltb0dad0b0b7033f78"
},
"SYS_ACL":{
}
},
{
"name":"Content Manager",
"description":null,
"uid":"blt6c7ffc6b4906acf5",
"created_by":"blta7eaf6883dd73a0b",
"updated_by":"blt1fd0057b90905592",
"created_at":"2021-09-16T11:54:15.300Z",
"updated_at":"2021-09-23T15:29:44.813Z",
"roles":[
],
"users":[
"blt1fd0057b90905592"
],
"owner":"[email protected]",
"stack":{
"created_at":"2021-09-16T11:54:14.172Z",
"updated_at":"2021-09-16T12:29:24.179Z",
"uid":"blt48b5e7f7b2f4b962",
"name":"My Site",
"description":"My site related content.",
"org_uid":"blteac54a27425b3b0e",
"api_key":"blt29ec365eaa0c8d67",
"master_locale":"en-us",
"is_asset_download_public":true,
"owner_uid":"blta7eaf6883dd73a0b",
"user_uids":[
"blta7eaf6883dd73a0b",
"blt1fd0057b90905592"
],
"settings":{
"version":"2019-04-30",
"rte_version":3,
"blockAuthQueryParams":true,
"allowedCDNTokens":[
"access_token"
],
"branches":true,
"webhook_enabled":true,
"stack_variables":{
},
"live_preview":{
},
"discrete_variables":{
"cms":true,
"_version":3,
"secret_key":"6ab0a6df0447b33386648f1d889d27b253ffe7fc"
},
"language_fallback":false,
"workflow_stages":true,
"publishing_rules":true
},
"master_key":"bltb0dad0b0b7033f78"
},
"SYS_ACL":{
}
},
{
"name":"Admin",
"description":"Admin can perform all actions and manage all settings of the stack, except the ability to delete or transfer ownership of the stack.",
"uid":"bltc5412bb640c8cce1",
"created_by":"blta7eaf6883dd73a0b",
"updated_by":"blta7eaf6883dd73a0b",
"created_at":"2021-09-16T11:54:15.300Z",
"updated_at":"2021-09-16T11:54:15.300Z",
"users":[
"blt1fd0057b90905592"
],
"owner":"[email protected]",
"stack":{
"created_at":"2021-09-16T11:54:14.172Z",
"updated_at":"2021-09-16T12:29:24.179Z",
"uid":"blt48b5e7f7b2f4b962",
"name":"My Site",
"description":"My site related content.",
"org_uid":"blteac54a27425b3b0e",
"api_key":"blt29ec365eaa0c8d67",
"master_locale":"en-us",
"is_asset_download_public":true,
"owner_uid":"blta7eaf6883dd73a0b",
"user_uids":[
"blta7eaf6883dd73a0b",
"blt1fd0057b90905592"
],
"settings":{
"version":"2019-04-30",
"rte_version":3,
"blockAuthQueryParams":true,
"allowedCDNTokens":[
"access_token"
],
"branches":true,
"webhook_enabled":true,
"stack_variables":{
},
"live_preview":{
},
"discrete_variables":{
"cms":true,
"_version":3,
"secret_key":"6ab0a6df0447b33386648f1d889d27b253ffe7fc"
},
"language_fallback":false,
"workflow_stages":true,
"publishing_rules":true
},
"master_key":"bltb0dad0b0b7033f78"
},
"SYS_ACL":{
}
}
]
}Get a single role
https://api.contentstack.io/v3/roles/{role_uid}?include_permissions={include_permissions}&include_rules={include_rules}The Get a single role request returns comprehensive information on a specific role.
To configure the permissions for your application via OAuth, please include the cm.roles.management:read scope.
{
"role":{
"name":"Developer",
"description":"Developer can perform all Content Manager's actions, view audit logs, create roles, invite users, manage content types, languages, and environments.",
"uid":"bltf177eec8730751a3",
"created_by":"blta7eaf6883dd73a0b",
"updated_by":"blta7eaf6883dd73a0b",
"created_at":"2021-09-16T11:54:15.300Z",
"updated_at":"2021-09-16T12:29:24.192Z",
"roles":[
],
"users":[
"blt1fd0057b90905592"
],
"owner":"[email protected]",
"stack":{
"created_at":"2021-09-16T11:54:14.172Z",
"updated_at":"2021-09-16T12:29:24.179Z",
"uid":"blt48b5e7f7b2f4b962",
"name":"My Site",
"description":"My site related content.",
"org_uid":"blteac54a27425b3b0e",
"api_key":"blt29ec365eaa0c8d67",
"master_locale":"en-us",
"is_asset_download_public":true,
"owner_uid":"blta7eaf6883dd73a0b",
"user_uids":[
"blta7eaf6883dd73a0b",
"blt1fd0057b90905592"
],
"settings":{
"version":"2019-04-30",
"rte_version":3,
"blockAuthQueryParams":true,
"allowedCDNTokens":[
"access_token"
],
"branches":true,
"webhook_enabled":true,
"stack_variables":{
},
"live_preview":{
},
"discrete_variables":{
"cms":true,
"_version":3,
"secret_key":"6ab0a6df0447b33386648f1d889d27b253ffe7fc"
},
"language_fallback":false,
"workflow_stages":true,
"publishing_rules":true
},
"master_key":"bltb0dad0b0b7033f78"
},
"SYS_ACL":{
}
}
}Create a role
https://api.contentstack.io/v3/rolesThe Create a role request creates a new role in a stack.
In the 'Body' section, mention the role name, description, users, additional roles, rules (includes the actions that can be performed on entries, fields, and/or assets), and permissions (which include the details of the content types, taxonomies, environments, and languages that are accessible).
To configure the permissions for your application via OAuth, please include the cm.roles.management:write scope.
NoteYou can also restrict access to the master language entry while defining permissions for a new role. Refer to our Manage Language Permissions documentation for more details.
To add customized exceptions for all or specific languages, add an additional locale module in the request body. Under this module, pass the following parameters:
- locales: Specify the unique IDs of the languages for which you want to add exception rules
- sub_acl: Add this under acl. Here, specify the permissions you want to restrict for the languages specified in the above parameter, e.g., "create":true
- restrict: true: Set this parameter to true to enable exception rules for the specified languages
Here’s what your request body should look like:
{
"module":"locale",
"locales":[
"blt**************e8"
],
"acl":{
"read":true,
"sub_acl":{
"read":false,
"create":false,
"update":true,
"delete":false
}
},
"restrict":true
}
NoteLanguage-related exceptions can be added only for custom roles and the developer and content manager system roles.
When creating a user role, you need to specify the branch and alias scope through the following schema in the request body:
{
"module":"branch",
"branches":[
"main"
],
"acl":{
"read":true
}
},
{
"module":"branch_alias",
"branch_aliases":[
"deploy"
],
"acl":{
"read":true
}
}
To add taxonomy specific permissions, follow the following schema in your request body:
{
"module": "taxonomy",
"taxonomies": ["regions"],
"terms": ["regions.north_america"],
"content_types": [
{
"uid": "$all",
"acl": {
"read": true,
"sub_acl": {
"read": true,
"create": true,
"update": true,
"delete": true,
"publish": true
}
}
}
],
"acl": {
"read": true,
"sub_acl": {
"read": true,
"create": true,
"update": true,
"delete": true,
"publish": true
}
}
}{
"role":{
"name": "Regional Custom Role",
"description": "",
"rules": [
{
"module": "branch",
"branches": [
"main"
],
"acl": {
"read": true
}
},
{
"module": "environment",
"environments": ["blt**************ad", "blt**************b4"],
"acl": {
"read": true
}
},
{
"module": "locale",
"locales": ["blt**************46", "blt**************88"],
"acl": {
"read": true
}
},
{
"module": "taxonomy",
"taxonomies": ["regions"],
"terms": ["regions.north_america"],
"content_types": [
{
"uid": "$all",
"acl": {
"read": true,
"sub_acl": {
"read": true,
"create": true,
"update": true,
"delete": true,
"publish": true
}
}
}
],
"acl": {
"read": true,
"sub_acl": {
"read": true,
"create": true,
"update": true,
"delete": true,
"publish": true
}
}
},
{
"module": "content_type",
"content_types": ["marketing_blogs"],
"acl": {
"read": true,
"sub_acl": {
"read": true,
"create": true,
"update": true,
"delete": true,
"publish": true
}
}
}
],
"users": [],
"uid": "blt**************09",
"org_uid": "blt**************c6",
"api_key": "blt**************af"
}
}{
"notice": "The role created successfully.",
"role": {
"name": "Regional Custom Role",
"description": "",
"rules": [
{
"module": "branch",
"branches": [
"main"
],
"acl": {
"read": true
}
},
{
"module": "environment",
"environments": [
"blt**************ad",
"blt**************b4"
],
"acl": {
"read": true
}
},
{
"module": "locale",
"locales": [
"blt**************46",
"blt**************88"
],
"acl": {
"read": true
}
},
{
"module": "taxonomy",
"taxonomies": [
"regions"
],
"terms": [
"regions.north_america"
],
"content_types": [
{
"uid": "$all",
"acl": {
"read": true,
"sub_acl": {
"read": true,
"create": true,
"update": true,
"delete": true,
"publish": true
}
}
}
],
"acl": {
"read": true,
"sub_acl": {
"read": true,
"create": true,
"update": true,
"delete": true,
"publish": true
}
}
},
{
"module": "content_type",
"content_types": [
"marketing_blogs"
],
"acl": {
"read": true,
"sub_acl": {
"read": true,
"create": true,
"update": true,
"delete": true,
"publish": true
}
}
}
],
"users": [],
"uid": "blt**************c3",
"org_uid": "blt**************c6",
"api_key": "blt**************af",
"created_by": "blt**************96",
"updated_by": "blt**************96",
"created_at": "2024-05-29T09:49:16.952Z",
"updated_at": "2024-05-29T09:49:16.952Z"
}
}Update role
https://api.contentstack.io/v3/roles/{role_uid}The Update role request lets you modify an existing role of your stack. However, the pre-existing system roles cannot be modified.
In the 'Body' section, include the updated details of the role which include name, description, users, additional roles, rules (includes the actions that can be performed on entries, fields, and/or assets), and permissions (which include the details of the content types, taxonomies, environments, and languages that are accessible).
To configure the permissions for your application via OAuth, please include the cm.roles.management:write scope.
NoteYou can also restrict access to the master language entry while defining permissions for a new role.
To add customized exceptions for all or specific languages, add an additional locale module in the request body. Under this module, pass the following parameters:
- locales: Specify the unique IDs of the languages for which you want to add exception rules
- sub_acl: Add this under acl. Here, specify the permissions you want to restrict for the languages specified in the above parameter, e.g., "create":true
- restrict: true: Set this parameter to true to enable exception rules for the specified languages
Here’s what your request body should look like:
{
"module":"locale",
"locales":[
"blt008a444c98ab47e8"
],
"acl":{
"read":true,
"sub_acl":{
"read":false,
"create":false,
"update":true,
"delete":false
}
},
"restrict":true
}
NoteLanguage-related exceptions can be added only for custom roles and the developer and content manager system roles.
When updating a user role, you need to specify the branch and alias scope through the following schema in the request body:
{
"module":"branch",
"branches":[
"main"
],
"acl":{
"read":true
}
},
{
"module":"branch_alias",
"branch_aliases":[
"deploy"
],
"acl":{
"read":true
}
}
To add taxonomy specific permissions, follow the following schema in your request body:
{
"module": "taxonomy",
"taxonomies": ["regions"],
"terms": ["regions.north_america", "regions.south_america"],
"content_types": [
{
"uid": "$all",
"acl": {
"read": true,
"sub_acl": {
"read": true,
"create": true,
"update": true,
"delete": true,
"publish": true
}
}
}
],
"acl": {
"read": true,
"sub_acl": {
"read": true,
"create": true,
"update": true,
"delete": true,
"publish": true
}
}
}{
"role":{
"name": "Updated Regional Custom Role",
"description": "",
"rules": [
{
"module": "branch",
"branches": [
"main"
],
"acl": {
"read": true
}
},
{
"module": "environment",
"environments": ["blt**************ad", "blt**************b4"],
"acl": {
"read": true
}
},
{
"module": "locale",
"locales": ["blt**************46", "blt**************88"],
"acl": {
"read": true
}
},
{
"module": "taxonomy",
"taxonomies": ["regions"],
"terms": ["regions.north_america", "regions.south_america"],
"content_types": [
{
"uid": "$all",
"acl": {
"read": true,
"sub_acl": {
"read": true,
"create": true,
"update": true,
"delete": true,
"publish": true
}
}
}
],
"acl": {
"read": true,
"sub_acl": {
"read": true,
"create": true,
"update": true,
"delete": true,
"publish": true
}
}
},
{
"module": "content_type",
"content_types": ["marketing_blogs"],
"acl": {
"read": true,
"sub_acl": {
"read": true,
"create": true,
"update": true,
"delete": true,
"publish": true
}
}
}
],
"users": [],
"uid": "blt**************09",
"org_uid": "blt**************c6",
"api_key": "blt**************af"
}
}{
"notice": "The role updated successfully.",
"role": {
"name": "Updated Regional Custom Role",
"description": "",
"rules": [
{
"module": "branch",
"branches": [
"main"
],
"acl": {
"read": true
}
},
{
"module": "environment",
"environments": [
"blt**************ad",
"blt**************b4"
],
"acl": {
"read": true
}
},
{
"module": "locale",
"locales": [
"blt**************46",
"blt**************88"
],
"acl": {
"read": true
}
},
{
"module": "taxonomy",
"taxonomies": [
"regions"
],
"terms": [
"regions.north_america",
"regions.south_america"
],
"content_types": [
{
"uid": "$all",
"acl": {
"read": true,
"sub_acl": {
"read": true,
"create": true,
"update": true,
"delete": true,
"publish": true
}
}
}
],
"acl": {
"read": true,
"sub_acl": {
"read": true,
"create": true,
"update": true,
"delete": true,
"publish": true
}
}
},
{
"module": "content_type",
"content_types": [
"marketing_blogs"
],
"acl": {
"read": true,
"sub_acl": {
"read": true,
"create": true,
"update": true,
"delete": true,
"publish": true
}
}
}
],
"users": [],
"uid": "blt**************c3",
"org_uid": "blt**************c6",
"api_key": "blt**************af",
"created_by": "blt**************96",
"updated_by": "blt**************96",
"created_at": "2024-05-29T09:49:16.952Z",
"updated_at": "2024-05-29T09:51:40.141Z"
}
}Delete role
https://api.contentstack.io/v3/roles/{role_uid}The Delete role call deletes an existing role from your stack.
To configure the permissions for your application via OAuth, please include the cm.roles.management:write scope.
{
"notice": "The role deleted successfully."
}