This API updates the role assigned to a member.
This is the authentication key required for requests.
Enable “Change member roles” in the Management API permissions, and include the key 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 member to update.
You can find the member ID on the member details page in the Administration console or in the response from the Get Member Information API (list, details).
Specify the roles to assign to the member after the update.
You can find role IDs in roles[].id in the response from the Get Roles API (GET /api/v1/roles). You can find the role IDs currently assigned to the member in roleIds in the response from the Get Member API.
Property | Type | Required | Description |
|---|---|---|---|
| array | Required | An array of Role IDs to assign after the update. Specify one or more Role IDs that exist in the target Service as an array of strings. Empty arrays ( |
All assigned roles are replaced with the contents of the submitted roleIds. Include any existing role IDs you want to retain in roleIds when submitting.
The following example replaces the roles assigned to a member with the two specified roles.
curl -X PATCH 'https://[サービスID].microcms-management.io/api/v1/members/[メンバーID]' \
-H 'X-MICROCMS-API-KEY: [APIキー]' \
-H 'Content-Type: application/json' \
-d '{
"roleIds": [
"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz"
]
}'To add roles, specify all the role IDs you want to keep, along with the IDs of the roles you want to add. To remove roles, specify only the IDs of the roles you want to keep.
A 200 response is returned when the role is updated successfully.
For status codes returned in the event of an error, see Error Response.
When the role is updated successfully, a response like the following is returned. The format is the same as the response from the Get Member API (GET /api/v1/members/{member_id}).
{
"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"name": "test-member",
"email": "test@microcms.co.jp",
"roleIds": [
"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz"
],
"mfa": true,
"lastAccessedAt": "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 specified role does not exist in the target Service (including roles from another Service) |
| The request is made for an environment created using the Multiple Environments feature |
| The specified Member does not exist in the target Service |
| The specified Member has a pending invitation |
| After the update, no joined Member with the Administrator role would remain in the target Service |
| The request body exceeds 1 MiB |
You can check the error details in message in the response body. For example, if you specify an empty array for roleIds, the following response is returned.
{
"message": "\"roleIds\" must not be empty"
}For other errors, see Management API Error Responses.
You cannot update the roles assigned to members who have been invited but have not yet joined.
After the update, at least one joined member must remain an administrator. Invited members are not counted as administrators.
Requests to environments created using the Multiple Environments feature are not supported.
Changing the roles assigned to members in the parent Service does not affect the roles assigned to members in child environments.
If the same member is updated concurrently, the role settings saved last will be applied.
Delete and update roles sequentially; do not perform these operations concurrently.
If the administrator role is removed from multiple administrators at the same time, no joined administrators may remain. Remove the administrator role sequentially as well.