This API retrieves a list of Roles for the Service.
This is the authentication key required for requests.
Enable “Get Roles (List and Details)” in the Management API permissions, and include the key in the request header 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).
Specify the number of roles to retrieve.
If omitted or set to an integer less than or equal to 0, the value is treated as the default value of 10.
If a value greater than 100 or a value that cannot be interpreted as an integer is specified, a 400 response is returned.
Specify the token to use for pagination.
To retrieve the next set of data, specify the token value included in the response in the next request.
Specify the token value included in the previous response as the token query parameter.
curl -H 'X-MICROCMS-API-KEY: [APIキー]' 'https://[サービスID].microcms-management.io/api/v1/roles?limit=10&token=[トークン]'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.
{
"roles": [
{
"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"
},
{
...
}
],
"totalCount": 5,
"token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}The response includes the following data.
An array of roles. They are returned in the same order as the role list in the Administration console.
The contents of each role object are the same as those in the response to "GET /api/v1/roles/{role_id}".
The total number of roles.
A token used for pagination.
Specify the returned value in the token query parameter of the next request. Repeat this process until token is no longer included in the response to retrieve all roles.
Note that a request specifying token may return an empty array.
Status Code | Condition |
|---|---|
| When a value greater than 100 is specified for |
| When a request is made to an environment created using the Multiple Environments feature |
For other errors, see Management API Error Responses.
Requests to environments created using the Multiple Environments feature are not supported.