This API retrieves detailed information about any Role.
This is the authentication key required for requests.
Enable “Get Roles (List and Details)” in the Management API permissions, and include it in the request headers when sending a 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).
Specify the ID of the Role to retrieve.
You can find the Role ID in the id field of the response from the API for retrieving the Role list. The ROLE# prefix is not required.
If the request is successful, a 200 response is returned.
For status codes returned in the event of an error, see Error Responses.
If the request is successful, the following response is returned.
{
"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"name": "Content Editor",
"isAdmin": false,
"permissions": {
"defaultPermissions": { ... },
"individualPermissions": [ ... ]
},
"createdAt": "2026-01-01T00:00:00.000Z",
"updatedAt": "2026-01-01T00:00:00.000Z"
}The response contains the following data.
Value | Description | |
|---|---|---|
| The role ID. | |
| The role name. | |
| Indicates whether this is an administrator role. | |
|
| The default Permission settings. |
| The API Custom Permission settings. | |
| The date and time the role was created. | |
| The date and time the role was updated. | |
permissions returns the same permission settings as those displayed on the role settings page in the Administration console.
For the Administrator role, all permissions are returned as enabled, and individualPermissions is always an empty array ([]).
The values of each key in permissions are as follows. The descriptions correspond to the item names on the role settings page in the Administration console.
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.
For example, members → read → level represents members.read.level, which appears in the response as follows:
"members": {
"read": {
"level": "ALL"
}
}Key | Type | Description | ||
|---|---|---|---|---|
|
|
| string | Member read permission |
| array | IDs of members who can be viewed | ||
| boolean | Invite members | ||
| boolean | Change the role assigned to a member | ||
| boolean | Delete members | ||
|
|
| string | Role read permission |
| boolean | Create roles | ||
| boolean | Change permission settings | ||
| boolean | Delete roles | ||
|
| boolean | Access the billing settings page | |
| boolean | Change the Plan and credit card | ||
|
| boolean | Access the API Key settings page | |
|
| boolean | View usage | |
|
|
| string | Environment read permission |
| array | Service IDs of environments that can be viewed | ||
| boolean | Create environments | ||
| boolean | Delete environments | ||
| object | Permissions related to reviews | ||
|
|
| string | Media read permission |
| boolean | Upload media | ||
| boolean | Edit the File Name / Alt Text | ||
| boolean | Delete media | ||
|
| boolean | Read APIs | |
| boolean | Create APIs | ||
| boolean | Manage API Settings and | ||
| boolean | Delete APIs | ||
| object | Permissions related to Content | ||
|
| boolean | View developer settings | |
An array of Custom Permissions configured for each API. If no Custom Permissions are configured, this is an empty array ([]).
Each element in the array is as follows.
Key | Type | Description | |
|---|---|---|---|
| string | Endpoint of the target API | |
|
| boolean | Read access to the API |
| boolean | Create, edit, and delete API Settings and Custom Fields | |
| boolean | Delete the API | |
| object | Permissions related to Content | |
|
| boolean | Display developer settings |
| object | Permissions related to Reviews | |
Common to defaultPermissions.content and individualPermissions[].content.
Key | Type | Description | |
|---|---|---|---|
|
| string | Content read permission |
|
| boolean | Save Draft |
| boolean | Publish | |
|
| boolean | Save Draft |
| boolean | Discard Draft | |
| boolean | Revert Unpublished Content to Draft | |
| boolean | Change the Content ID of Unpublished Content | |
| boolean | Reorder Unpublished Content | |
| boolean | Change the publication date of Unpublished Content | |
| boolean | Change the Content author | |
| boolean | Change the draftKey | |
| boolean | Publish or schedule publication of unapproved Content | |
| boolean | Publish or schedule publication of approved Content | |
| boolean | Unpublish or schedule unpublishing of unapproved Content | |
| boolean | Unpublish or schedule unpublishing of approved Content | |
| boolean | Revert Published Content to Draft | |
| boolean | Change the Content ID of Published Content | |
| boolean | Reorder Published Content | |
| boolean | Change the publication date of Published Content | |
| boolean | Delete Content | |
Common to defaultPermissions.reviews and individualPermissions[].reviews.
Key | Type | Description | |
|---|---|---|---|
|
| string | Permission to read Review Requests |
| boolean | Submit Review Requests | |
|
| string | Permission to edit Review Requests |
Status Code | Condition |
|---|---|
| When a role ID that is not in UUID format is specified |
| When a request is made to a child environment |
| When a nonexistent role is specified |
For other errors, see Management API Error Responses.
Requests to environments created using the Multiple Environments feature are not supported.