microCMS
Documentation
  • Pricing
  • Blog
  • FAQ
  • Contact
  • Sign In
  • Get started for free
Navigation
Tutorial
Next.js
  • Integration with Next.js
  • Getting Started with App Router
  • Tutorial (App Router)
  • Getting Started with Pages Router
  • Tutorial (Pages Router)
Astro
  • Getting Started
  • Integration with Astro
  • Tutorial
Nuxt
  • Integration with Nuxt
  • Getting Started
  • Tutorial
Gatsby
  • Integration with Gatsby
  • Getting Started
  • Tutorial
JavaScript
  • Integration with JavaScript
  • Getting Started (Browser)
  • Getting Started (Server)
PHP
  • Integration with PHP
  • Getting Started
Ruby
  • Integration with Ruby
  • Getting Started
Go
  • Integration with Go
  • Getting Started with microCMS
Manual
  • Introduction
Account & Login
  • Account Registration
  • Login
  • Email Address Authentication
Services
  • Creating a Service
  • Service Configuration
  • Template
  • Service Deletion
Payment
  • Change of Pricing Plan
  • Registering and Changing Payment Methods
API
  • Creating and Managing APIs
  • API Settings
  • Export/Import of API Schema
Fields
  • Text Field
  • Text Area
  • Image
  • Multiple Images
  • Date
  • Boolean
  • Selectable Field
  • Content Reference
  • Multiple Content References
  • Number
  • File
  • Extended Field
  • Repetition
  • Custom
Contents
  • CSV Export of Content
  • Content Creation
  • Content Editing
  • Content Management
  • View
  • Content Status
  • Custom Status
  • Setting the Content ID
  • Automatically Assigned Values for Content
  • CSV Import of Content
  • API Preview
  • Examples of Using Query Parameters with API Preview
  • Integration Methods by Rendering Type
  • Screen Preview
  • Setting Up Webhooks for Content
Rich Editor
  • How to Use the Rich Editor
  • Rich Editor WRITE API
  • How to Use the Old Rich Editor
Reviews
  • Review
  • AI Review
Media
  • Media Management
  • Changing Media Filters and Display Order
  • Media Tag Configuration
  • Setting Up Media Webhooks
  • Custom Domain Settings for Media
Permission Management
  • Member Management
  • Roles (Permission Management in the Admin Panel)
Environments
  • Multiple Environments (Development Environment)
  • Merging API Settings Between Environments
Connection
  • Amazon S3 Integration
Logs
  • Audit Log
  • Data Transfer Volume
Security
  • Content Update History
  • IP Restrictions for Management Dashboard
  • IP Restrictions for APIs
Authentication
  • Setting Up Two-Factor Authentication
  • Mandatory Two-Factor Authentication
  • Single Sign-On
Specifications & Limitations
  • Recommended Environment
  • Limitations / Precautions
Content API
  • What is the Content API?
Basic Operations
  • GET /api/v1/{endpoint}
  • GET /api/v1/{endpoint}/{content_id}
  • POST /api/v1/{endpoint}
  • PUT /api/v1/{endpoint}/{content_id}
  • PATCH /api/v1/{endpoint}/{content_id}
  • DELETE /api/v1/{endpoint}/{content_id}
API Keys
  • API Key (API Authentication and Authorization Management)
  • Migration from the Old API (X-API-KEY, etc.)
Responses & Error Handling
  • Response format for each field in the GET API
  • Specifying Query Parameters in the GET API
  • Error Responses of the Content API
Management API (Beta)
  • POST /api/v1/roles
  • DELETE /api/v1/roles/{role_id}
  • GET /api/v1/roles/{role_id}
  • PATCH /api/v1/roles/{role_id}
  • GET /api/v1/roles
  • What is the Management API?
Content Operations
  • PUT /api/v1/contents/{endpoint}/{content_id}/reservation
  • GET /api/v1/contents/{endpoint}
  • GET /api/v1/contents/{endpoint}/{content_id}
  • PATCH /api/v1/contents/{endpoint}/{content_id}/status
  • PATCH /api/v1/contents/{endpoint}/{content_id}/createdBy
Media Operations
  • GET /api/v2/media
  • GET /api/v1/media
  • POST /api/v1/media
  • DELETE /api/v2/media
Member Operations
  • PATCH /api/v1/members/{member_id}
  • GET /api/v1/members
  • GET /api/v1/members/{member_id}
API Operations
  • POST /api/v1/apis
  • GET /api/v1/apis
  • GET /api/v1/apis/{endpoint}
Service Operations
  • GET /api/v1/service
Responses & Error Handling
  • Management API Error Responses
Image API
  • What is the Image API?
Parameters
  • Image Size
  • Quality
  • Resolution and Screen Size
  • Format
  • Text
  • Border
  • Padding
  • Shape
  • Download
  • Watermark
MCP Server
  • microCMS MCP
  • microCMS Document MCP Server
  • Top
  • Management API (Beta)

GET /api/v1/roles

Last updated: 2026/11/17

This API retrieves a list of Roles for the Service.

Request Headers

X-MICROCMS-API-KEY

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.

Caution

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).

Query Parameters

limit

Specify the number of roles to retrieve.

  • Default value: 10
  • Maximum value: 100

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.

token

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.

Retrieving the next set of data

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=[トークン]'

Response

Status Code

If the request is successful, a 200 response is returned.
For status codes returned in the event of an error, see Error Responses.

Response Body

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.

roles

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}".

totalCount

The total number of roles.

token

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.

Error Response

Status Code

Condition

400

When a value greater than 100 is specified for limit, or an invalid token is specified

403

When a request is made to an environment created using the Multiple Environments feature

For other errors, see Management API Error Responses.

Limitations

Using Multiple Environments

Requests to environments created using the Multiple Environments feature are not supported.

Contents

  • Request Headers
  • X-MICROCMS-API-KEY
  • Query Parameters
  • limit
  • token
  • Response
  • Status Code
  • Response Body
  • Error Response
  • Limitations
  • Using Multiple Environments
  • Company
  • Legal Notice
  • Terms of Service
  • Privacy Policy

Copyright © microcms.io All rights reserved.