サービスのロールを更新するAPIです。
X-MICROCMS-API-KEYが判別できると、第三者による不正なコンテンツの操作が可能となります。お取り扱いには十分ご注意ください。詳細は「APIキー(APIの認証と権限管理)」をご覧ください。
送信するデータの形式を指定します。
microCMSではJSON形式のデータのみ扱っているため、application/json と指定してください。
更新する項目を指定します。nameとpermissionsはどちらも任意ですが、少なくとも一方を指定してください。指定しなかった項目は変更されません。
プロパティ | 型 | 指定要否 | 説明 |
|---|---|---|---|
| string | 任意 | ロール名です。1〜100文字で指定します。 |
| object | 任意 | ロールの権限設定です。指定した場合は、権限設定全体を置き換えます。 |
未定義のプロパティや、isAdmin・id・createdAt・updatedAt を指定した場合は、400 レスポンスが返却されます。
permissions は、一部の権限だけを更新することはできません。送信した内容で権限設定全体が置き換わり、送信しなかった個別権限は削除されます。
個別権限をすべて削除する場合は、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": "コンテンツ編集者(改)" }'以下は、ロール詳細取得APIで取得した現在の権限設定をもとに、お支払い設定画面へのアクセス権限(billing.read)を有効にする例です。
この例では、APIキーのマネジメントAPI権限で「ロールの取得 (一覧・詳細)」と「ロールの更新」を有効にしてください。
1. 現在のロール情報を取得する
curl -H 'X-MICROCMS-API-KEY: [APIキー]' \
'https://[サービスID].microcms-management.io/api/v1/roles/[ロールID]'
2. リクエストボディを用意する
取得に成功したことを確認し、レスポンスのpermissionsをコピーします。defaultPermissions.billing.readをtrueに変更し、変更後のpermissionsを次の形式でrole.jsonに保存します。
{
"permissions": 取得して編集した権限設定
}実際のファイルには、取得したpermissionsオブジェクト全体を指定してください。維持したい個別権限も含めます。idやisAdminなど、レスポンスのその他のプロパティは含めないでください。
3. 更新する
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.json正常にロールを更新できた場合は、200レスポンスが返却されます。
エラー時のステータスコードについては、「エラーレスポンス」をご覧ください。
正常にロールを更新できた場合は、以下のようなレスポンスが返却されます。
形式は「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-02T00:00:00.000Z"
}本APIで返却される主なエラーは以下のとおりです。
ステータスコード | 条件 |
|---|---|
| UUID形式ではないロールID(英大文字を含むUUIDを含む)を指定した場合 |
|
|
| リクエストボディが不正な場合( |
| 存在しないメンバー・環境・APIを指定した場合(招待中のメンバー、他のサービスのメンバーや環境を含む) |
| 管理者ロールを指定した場合 |
| 複数環境機能で作成した環境に対してリクエストした場合 |
| サービスに存在しないロールを指定した場合 |
| リクエストボディのサイズが1MiBを超える場合 |
エラーの詳細は、レスポンスボディのmessageで確認できます。
たとえば、nameとpermissionsのどちらも指定しなかった場合は、次のようなレスポンスが返却されます。
{ "message": "Either \"name\" or \"permissions\" is required" }その他のエラーについては、「マネジメントAPIのエラーレスポンス」をご覧ください。