サービスにロールを作成するAPIです。
本APIは、ロール機能を利用できるプラン(Business、Enterprise)で利用可能です。ロール機能を利用できないプランでは、エラーが返却されます。
X-MICROCMS-API-KEYが判別できると、第三者による不正なコンテンツの操作が可能となります。お取り扱いには十分ご注意ください。詳細は「APIキー(APIの認証と権限管理)」をご覧ください。
送信するデータの形式を指定します。
microCMSではJSON形式のデータのみ扱っているため、application/json と指定してください。
作成するロールのロール名と権限設定を指定します。
プロパティ | 型 | 指定要否 | 説明 |
|---|---|---|---|
| string | 必須 | ロール名。1〜100文字で指定します。既存のロールと同じ名前も指定できます。 |
| object | 必須 | ロールの権限設定。 |
未定義のプロパティや、isAdmin・id・createdAt・updatedAt を指定した場合は、400 レスポンスが返却されます。
permissions 内のキーは、すべて指定が必要です。利用しない権限も、false や NONE を指定してください。キーの省略やnull、型の異なる値を指定した場合は、400 レスポンスが返却されます。
ロール詳細取得API(GET /api/v1/roles/{role_id})のレスポンスの name と permissions をそのまま送信すると、同じ権限設定のロールを作成できます。既存のロールをもとに作成する場合にご利用ください。
デフォルト権限です。level は文字列、memberIds・serviceIds は文字列の配列で指定します。各操作の許可・不許可はboolean型で指定します。
各キーの意味と、管理画面のロール設定画面の項目名との対応は、「GET /api/v1/roles/{role_id}」の「権限の詳細」をご覧ください。
キー列は、JSONの階層ごとに列を分けて表示しています。左の列から順に「.」でつなげたものが、実際のキーになります。
例:members → read → level は members.read.level を表し、リクエストボディでは次のように指定します。
"members": {
"read": {
"level": "ALL"
}
}キー | 型 | 指定できる値 | ||
|---|---|---|---|---|
|
|
| string |
|
| array | 閲覧を許可するメンバーのIDの配列 | ||
| boolean |
| ||
| boolean |
| ||
| boolean |
| ||
|
|
| string |
|
| boolean |
| ||
| boolean |
| ||
| boolean |
| ||
|
| boolean |
| |
| boolean |
| ||
|
| boolean |
| |
|
| boolean |
| |
|
|
| string |
|
| array | 閲覧を許可する環境のサービスIDの配列 | ||
| boolean |
| ||
| boolean |
| ||
| object | 「GET /api/v1/roles/{role_id}」の「reviewsの詳細」と同じキーをすべて指定 | ||
|
|
| string |
|
| boolean |
| ||
| boolean |
| ||
| boolean |
| ||
|
| boolean |
| |
| boolean |
| ||
| boolean |
| ||
| boolean |
| ||
| object | 「GET /api/v1/roles/{role_id}」の「contentの詳細」と同じキーをすべて指定 | ||
|
| boolean |
| |
environmentsの更新権限は管理者ロールのみが持つ権限のため、指定できません。content.updateには、以下の16項目をすべて指定します。saveDraft、removeDraft、revertToDraftUnpublished、changeContentIdUnpublished、reorderUnpublished、changePublicationDateUnpublished、changeAuthor、changeDraftKey、publish、publishApproved、unpublish、unpublishApproved、revertToDraft、changeContentIdPublished、reorderPublished、changePublicationDatePublishedキー | 指定できる値 |
|---|---|
|
|
|
|
|
|
|
|
|
|
members.read.memberIdsmembers.read.levelがSPECIFICの場合は必須です。SPECIFIC 以外の場合は、members.read.memberIds を省略してください。idから確認可能です。空の配列([])も指定できます。environments.read.serviceIdsenvironments.read.levelがRESTRICTEDの場合は必須です。RESTRICTED 以外の場合は、environments.read.serviceIds を省略してください。[])も指定できます。APIごとの個別権限の配列です。
個別権限を設定しない場合は、空の配列([])を指定してください。
キー | 型 | 指定できる値 | |
|---|---|---|---|
| string | 個別権限を設定するAPIのエンドポイント名(例: API名(表示名)は指定不可。大文字・小文字は区別され、同じエンドポイントを重複して指定するのは不可。 | |
|
| boolean |
|
| boolean |
| |
| boolean |
| |
| object |
| |
|
| boolean |
|
| object |
| |
以下は、すべてのコンテンツを編集・公開できる「コンテンツ編集者」ロールを作成する例です。
curl -X POST 'https://[サービスID].microcms-management.io/api/v1/roles' \
-H 'X-MICROCMS-API-KEY: [APIキー]' \
-H 'Content-Type: application/json' \
-d '{
"name": "コンテンツ編集者",
"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": []
}
}'上記の例の members と environments を、以下のように変更します。
"members": {
"read": { "level": "SPECIFIC", "memberIds": ["[メンバーID]"] },
"create": false,
"update": false,
"delete": false
},
"environments": {
"read": { "level": "RESTRICTED", "serviceIds": ["[環境のサービスID]"] },
"create": false,
"delete": false
}デフォルト権限の content と api を無効にしたうえで、individualPermissions で特定のAPI(この例では blog )の権限を設定する例です。
"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" } }
}
]正常にロールを作成できた場合は、201レスポンスが返却されます。
エラー時のステータスコードについては、「エラーレスポンス」をご覧ください。
正常にロールを作成できた場合は、以下のようなレスポンスが返却されます。
形式は「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"
}本APIで返却される主なエラーは以下のとおりです。
ステータスコード | 条件 |
|---|---|
| リクエストボディが不正な場合(必須キーの不足、 |
| 存在しないメンバー・環境・APIを指定した場合(招待中のメンバー、他のサービスのメンバーや環境を含む) |
| ロール機能を利用できないプランの場合 |
| 複数環境機能で作成した環境に対してリクエストした場合 |
| リクエストボディのサイズが1MiBを超える場合 |
エラーの詳細は、レスポンスボディのmessageで確認できます。
たとえば、content.update.publishを省略した場合は、次のようなレスポンスが返却されます。
{ "message": "\"permissions.defaultPermissions.content.update.publish\" is required" }その他のエラーについては、「マネジメントAPIのエラーレスポンス」をご覧ください。