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/{role_id}

Last updated: 2026/11/17

This API retrieves detailed information about any Role.

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 it in the request headers when sending a 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).

Path Parameters

role_id

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.

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.

{
  "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

id

The role ID.

name

The role name.

isAdmin

Indicates whether this is an administrator role.
true: administrator role, false: any other role

permissions

defaultPermissions

The default Permission settings.

individualPermissions

The API Custom Permission settings.
An array of Permission settings for each API. If not configured, this is an empty array ([]).

createdAt

The date and time the role was created.

updatedAt

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 ([]).

Permission Details

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

defaultPermissions (Default Permissions)

Key

Type

Description

members

read

level

string

Member read permission
・ALL: All members
・SAME_ROLE: Members assigned this role
・SPECIFIC: Specific members only
・NONE: None

memberIds

array

IDs of members who can be viewed
Returned only when members.read.level is SPECIFIC.
Returns an empty array ([]) if no members are specified.

create

boolean

Invite members

update

boolean

Change the role assigned to a member

delete

boolean

Delete members

roles

read

level

string

Role read permission
・ALL: All roles
・SAME_ROLE: Only roles you belong to
・NONE: None

create

boolean

Create roles

update

boolean

Change permission settings

delete

boolean

Delete roles

billing

read

boolean

Access the billing settings page

update

boolean

Change the Plan and credit card

apiKeys

read

boolean

Access the API Key settings page

usage

read

boolean

View usage
(Access the Data Transfer Amount and API Request Count pages)

environments

read

level

string

Environment read permission
・ALL: All environments
・URL_ONLY: Environments whose URLs are known (deprecated)
・RESTRICTED: Specific environments only
・NONE: None

serviceIds

array

Service IDs of environments that can be viewed
Returned only when environments.read.level is RESTRICTED.

create

boolean

Create environments

delete

boolean

Delete environments

reviews

object

Permissions related to reviews
For details, see "Details of reviews."

media

read

level

string

Media read permission
・ALL: All media
・SAME_ROLE: Only media created by members with this role
・CREATED: Only media you uploaded
・NONE: None

create

boolean

Upload media

update

boolean

Edit the File Name / Alt Text
Re-upload files / Set Media Tags

delete

boolean

Delete media

api

read

boolean

Read APIs
(e.g., display them in the sidebar and reference Content)

create

boolean

Create APIs

update

boolean

Manage API Settings and
create / edit / delete Custom Fields

delete

boolean

Delete APIs

content

object

Permissions related to Content
For details, see "Details of content."

developerMenu

read

boolean

View developer settings

individualPermissions (Custom Permissions)

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

apiId

string

Endpoint of the target API

api

read

boolean

Read access to the API
(such as displaying it in the sidebar and referencing Content)

update

boolean

Create, edit, and delete API Settings and Custom Fields

delete

boolean

Delete the API

content

object

Permissions related to Content
For details, see "Details of content."

developerMenu

read

boolean

Display developer settings

reviews

object

Permissions related to Reviews
For details, see "Details of reviews."

Content Details

Common to defaultPermissions.content and individualPermissions[].content.

Key

Type

Description

read

level

string

Content read permission
・ALL: All Content
・SAME_ROLE: Only Content created by members with this Role
・CREATED: Only Content created by the member
・NONE: None

create

draft

boolean

Save Draft

publish

boolean

Publish

update

saveDraft

boolean

Save Draft

removeDraft

boolean

Discard Draft

revertToDraftUnpublished

boolean

Revert Unpublished Content to Draft

changeContentIdUnpublished

boolean

Change the Content ID of Unpublished Content

reorderUnpublished

boolean

Reorder Unpublished Content

changePublicationDateUnpublished

boolean

Change the publication date of Unpublished Content

changeAuthor

boolean

Change the Content author

changeDraftKey

boolean

Change the draftKey

publish

boolean

Publish or schedule publication of unapproved Content

publishApproved

boolean

Publish or schedule publication of approved Content

unpublish

boolean

Unpublish or schedule unpublishing of unapproved Content

unpublishApproved

boolean

Unpublish or schedule unpublishing of approved Content

revertToDraft

boolean

Revert Published Content to Draft

changeContentIdPublished

boolean

Change the Content ID of Published Content

reorderPublished

boolean

Reorder Published Content

changePublicationDatePublished

boolean

Change the publication date of Published Content

delete

boolean

Delete Content

Details of reviews

Common to defaultPermissions.reviews and individualPermissions[].reviews.

Key

Type

Description

read

level

string

Permission to read Review Requests
・ALL: All Review Requests
・SAME_ROLE: Only Reviews created by members of this Role
・CREATED: Only Review Requests created by you
・NONE: None

create

boolean

Submit Review Requests

update

level

string

Permission to edit Review Requests
・ALL: Approve + edit
・EDIT: Edit
・NONE: None

Error Response

Status Code

Condition

400

When a role ID that is not in UUID format is specified

403

When a request is made to a child environment

404

When a nonexistent role is specified

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
  • Path Parameters
  • role_id
  • 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.