This API updates a Service's Role.
This is the authentication key required for requests.
Enable “Update 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 ID of the role to update.
You can find the role ID in the id field of the response from the API for retrieving the list of roles.
Specify the items to update.
Both name and permissions are optional, but you must specify at least one of them. Items you do not specify will remain unchanged.
Property | Type | Required | Description |
|---|---|---|---|
| string | Optional | The role name. Specify between 1 and 100 characters. |
| object | Optional | The role's permission settings. If specified, this replaces all permission settings. Specify both |
A 400 response is returned if you specify an undefined property or isAdmin, id, createdAt, or updatedAt.
permissions cannot be used to update only some permissions. The submitted data replaces the entire permission configuration, and any Custom Permissions not included in the request are deleted.
To remove all Custom Permissions, specify an empty array ([]) for individualPermissions.
curl -X PATCH 'https://[サービスID].microcms-management.io/api/v1/roles/[ロールID]' \
-H 'X-MICROCMS-API-KEY: [APIキー]' \
-H 'Content-Type: application/json' \
-d '{ "name": "コンテンツ編集者(改)" }'The following example enables access to the billing settings page (billing.read) based on the current permission settings retrieved using the Get Role Details API.
For this example, enable “Get roles (list and details)” and “Update roles” in the Management API permissions for the API Key.
1. Retrieve the current role information
curl -H 'X-MICROCMS-API-KEY: [APIキー]' \
'https://[サービスID].microcms-management.io/api/v1/roles/[ロールID]'
2. Prepare the request body
Confirm that the retrieval was successful, then copy permissions from the response. Change defaultPermissions.billing.read to true, and save the updated permissions in role.json in the following format.
{
"permissions": 取得して編集した権限設定
}In the actual file, specify the entire retrieved permissions object, including any Custom Permissions you want to retain. Do not include other response properties such as id or isAdmin.
3. Update the role
curl -X PATCH 'https://[サービスID].microcms-management.io/api/v1/roles/[ロールID]' \
-H 'X-MICROCMS-API-KEY: [APIキー]' \
-H 'Content-Type: application/json' \
-d @role.jsonIf the role is updated successfully, a 200 response is returned.
For status codes returned in case of an error, see "Error Response."
If the role is updated 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": "Content Editor (Updated)",
"isAdmin": false,
"permissions": {
"defaultPermissions": { ... },
"individualPermissions": [ ... ]
},
"createdAt": "2026-01-01T00:00:00.000Z",
"updatedAt": "2026-01-02T00:00:00.000Z"
}The main errors returned by this API are as follows.
Status Code | Condition |
|---|---|
| When a role ID that is not in UUID format is specified (including UUIDs containing uppercase letters) |
| When neither |
| When the request body is invalid (for example, only one of |
| When a nonexistent member, environment, or API is specified (including invited members and members or environments from other services) |
| When the Administrator role is specified |
| When a request is made for an environment created using the Multiple Environments feature |
| When a role that does not exist in the Service is specified |
| When the request body exceeds 1 MiB |
You can check the error details in the message field of the response body.
For example, if neither name nor permissions is specified, the following response is returned.
{ "message": "Either \"name\" or \"permissions\" is required" }For other errors, see Management API Error Responses.
The Administrator role cannot be updated.
Requests to environments created using the Multiple Environments feature are not supported.