This is an API for creating a Role in a Service.
This API is available on plans that support the Role feature (Business and Enterprise plans). An error is returned on plans that do not support the Role feature.
This is the authentication key required for requests.
Enable "Create Roles" in the Management API permissions and include it in the request headers when sending the request.
If the X-MICROCMS-API-KEY is exposed, third parties may be able to manipulate your Content without authorization. Please handle it with care. For details, see API Key (API Authentication and Permission Management).
Specifies the format of the data to send.
microCMS only supports JSON data, so specify application/json.
Specify the role name and permissions for the role to be created.
Property | Type | Required | Description |
|---|---|---|---|
| string | Required | Role name. Specify between 1 and 100 characters. You can use the same name as an existing role. |
| object | Required | Role permission settings. Specify both |
A 400 response is returned if you specify an undefined property or isAdmin, id, createdAt, or updatedAt.
All keys in permissions must be specified. For permissions you do not use, specify false or NONE. If you omit a key or specify null or a value of a different type, a 400 response will be returned.
You can create a role with the same permission settings by sending the name and permissions from the response of the Role Details API (GET /api/v1/roles/{role_id}) as is. Use this when creating a role based on an existing role.
Default permissions.
Specify level as a string and memberIds and serviceIds as arrays of strings. Specify whether each operation is allowed or denied as a boolean.
For the meaning of each key and its corresponding item in the Role settings screen in the Administration console, see “GET /api/v1/roles/{role_id}” under “Permission details.”
Each column in the Key column represents a level in the JSON hierarchy. Read the columns from left to right and join them with “.” to get the actual key.
Example: members → read → level represents members.read.level, which is specified in the request body as follows.
"members": {
"read": {
"level": "ALL"
}
}Key | Type | Allowed values | ||
|---|---|---|---|---|
|
|
| string |
|
| array | An array of IDs for members who are allowed to view | ||
| boolean |
| ||
| boolean |
| ||
| boolean |
| ||
|
|
| string |
|
| boolean |
| ||
| boolean |
| ||
| boolean |
| ||
|
| boolean |
| |
| boolean |
| ||
|
| boolean |
| |
|
| boolean |
| |
|
|
| string |
|
| array | An array of Service IDs for environments that are allowed to be viewed | ||
| boolean |
| ||
| boolean |
| ||
| object | Specify all the same keys as in “GET /api/v1/roles/{role_id}” under “Details of reviews” | ||
|
|
| string |
|
| boolean |
| ||
| boolean |
| ||
| boolean |
| ||
|
| boolean |
| |
| boolean |
| ||
| boolean |
| ||
| boolean |
| ||
| object | Specify all the same keys as in “GET /api/v1/roles/{role_id}” under “Details of content” | ||
|
| boolean |
| |
environments, so it cannot be specified.content.update, specify all 16 of the following items:saveDraft, removeDraft, revertToDraftUnpublished, changeContentIdUnpublished, reorderUnpublished, changePublicationDateUnpublished, changeAuthor, changeDraftKey, publish, publishApproved, unpublish, unpublishApproved, revertToDraft, changeContentIdPublished, reorderPublished, changePublicationDatePublishedKey | Available values |
|---|---|
|
|
|
|
|
|
|
|
|
|
members.read.memberIdsmembers.read.level is SPECIFIC. Omit members.read.memberIds otherwise.id field of the response from the API for retrieving the member list. An empty array ([]) can also be specified.environments.read.serviceIdsenvironments.read.level is RESTRICTED. Omit environments.read.serviceIds otherwise.[]) can also be specified.An array of Custom Permissions for each API.
If you do not set any Custom Permissions, specify an empty array ([]).
Key | Type | Allowed values | |
|---|---|---|---|
| string | The Endpoint name of the API for which to set Custom Permissions (e.g., The API name (Display Name) cannot be specified. Uppercase and lowercase letters are distinguished, and the same Endpoint cannot be specified more than once. | |
|
| boolean |
|
| boolean |
| |
| boolean |
| |
| object | Same format as | |
|
| boolean |
|
| object | Same format as | |
The following is an example of creating a “Content Editor” role that can edit and publish all content.
curl -X POST 'https://[サービスID].microcms-management.io/api/v1/roles' \
-H 'X-MICROCMS-API-KEY: [APIキー]' \
-H 'Content-Type: application/json' \
-d '{
"name": "Content Editor",
"permissions": {
"defaultPermissions": {
"roles": { "read": { "level": "NONE" }, "create": false, "update": false, "delete": false },
"members": { "read": { "level": "NONE" }, "create": false, "update": false, "delete": false },
"usage": { "read": false },
"environments": { "read": { "level": "NONE" }, "create": false, "delete": false },
"billing": { "read": false, "update": false },
"apiKeys": { "read": false },
"reviews": { "read": { "level": "ALL" }, "create": true, "update": { "level": "EDIT" } },
"media": { "read": { "level": "ALL" }, "create": true, "update": true, "delete": false },
"api": { "read": true, "create": false, "update": false, "delete": false },
"content": {
"read": { "level": "ALL" },
"create": { "draft": true, "publish": true },
"update": {
"saveDraft": true,
"removeDraft": true,
"revertToDraftUnpublished": true,
"changeContentIdUnpublished": true,
"reorderUnpublished": true,
"changePublicationDateUnpublished": true,
"changeAuthor": true,
"changeDraftKey": true,
"publish": true,
"publishApproved": true,
"unpublish": true,
"unpublishApproved": true,
"revertToDraft": true,
"changeContentIdPublished": true,
"reorderPublished": true,
"changePublicationDatePublished": true
},
"delete": true
},
"developerMenu": { "read": false }
},
"individualPermissions": []
}
}'Change members and environments in the example above as follows.
"members": {
"read": { "level": "SPECIFIC", "memberIds": ["[メンバーID]"] },
"create": false,
"update": false,
"delete": false
},
"environments": {
"read": { "level": "RESTRICTED", "serviceIds": ["[環境のサービスID]"] },
"create": false,
"delete": false
}This example disables content and api in the default permissions, then sets permissions for a specific API (in this example, blog) using individualPermissions.
"individualPermissions": [
{
"apiId": "blog",
"api": { "read": true, "update": false, "delete": false },
"content": {
"read": { "level": "ALL" },
"create": { "draft": true, "publish": true },
"update": {
"saveDraft": true,
"removeDraft": true,
"revertToDraftUnpublished": true,
"changeContentIdUnpublished": true,
"reorderUnpublished": true,
"changePublicationDateUnpublished": true,
"changeAuthor": true,
"changeDraftKey": true,
"publish": true,
"publishApproved": true,
"unpublish": true,
"unpublishApproved": true,
"revertToDraft": true,
"changeContentIdPublished": true,
"reorderPublished": true,
"changePublicationDatePublished": true
},
"delete": true
},
"developerMenu": { "read": false },
"reviews": { "read": { "level": "ALL" }, "create": true, "update": { "level": "EDIT" } }
}
]If the Role is created successfully, a 201 response is returned.
For status codes returned in case of an error, see "Error Responses."
If the Role is created successfully, a response like the following is returned.
The format is the same as the response for "GET /api/v1/roles/{role_id}."
{
"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"name": "コンテンツ編集者",
"isAdmin": false,
"permissions": {
"defaultPermissions": { ... },
"individualPermissions": []
},
"createdAt": "2026-01-01T00:00:00.000Z",
"updatedAt": "2026-01-01T00:00:00.000Z"
}The main errors returned by this API are as follows.
Status Code | Condition |
|---|---|
| The request body is invalid (for example, a required key is missing, a value is |
| A nonexistent member, environment, or API is specified (including invited members and members or environments from other Services) |
| The Plan does not support the Role feature |
| The request targets an environment created using the Multiple Environments feature |
| The request body exceeds 1 MiB |
You can check the error details in the message field of the response body.
For example, if content.update.publish is omitted, the following response is returned.
{ "message": "\"permissions.defaultPermissions.content.update.publish\" is required" }For other errors, see Management API Error Responses.
Administrator roles cannot be created.
Requests to environments created using the Multiple Environments feature are not supported.