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)

PATCH /api/v1/roles/{role_id}

Last updated: 2026/11/17

This API updates a Service's Role.

Request Headers

X-MICROCMS-API-KEY

This is the authentication key required for requests.
Enable “Update Roles” in the Management API permissions and include it in the request headers 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).

Content-Type

Specifies the format of the data to send.
microCMS only supports JSON data, so specify application/json.

Path Parameters

role_id

Specify the ID of the role to update.
You can find the role ID in the id field of the response from the API for retrieving the list of roles.

Request Body

Specify the items to update.
Both name and permissions are optional, but you must specify at least one of them. Items you do not specify will remain unchanged.

Property

Type

Required

Description

name

string

Optional

The role name. Specify between 1 and 100 characters.

permissions

object

Optional

The role's permission settings. If specified, this replaces all permission settings. Specify both defaultPermissions and individualPermissions. For details on the format and how to specify each key, see permissions in 「POST /api/v1/roles」.

A 400 response is returned if you specify an undefined property or isAdmin, id, createdAt, or updatedAt.

Information

permissions cannot be used to update only some permissions. The submitted data replaces the entire permission configuration, and any Custom Permissions not included in the request are deleted.
To remove all Custom Permissions, specify an empty array ([]) for individualPermissions.

Request Examples

Updating only the role name

curl -X PATCH 'https://[サービスID].microcms-management.io/api/v1/roles/[ロールID]' \
  -H 'X-MICROCMS-API-KEY: [APIキー]' \
  -H 'Content-Type: application/json' \
  -d '{ "name": "コンテンツ編集者(改)" }'

Changing part of the current permission settings

The following example enables access to the billing settings page (billing.read) based on the current permission settings retrieved using the Get Role Details API.
For this example, enable “Get roles (list and details)” and “Update roles” in the Management API permissions for the API Key.

1. Retrieve the current role information

curl -H 'X-MICROCMS-API-KEY: [APIキー]' \
  'https://[サービスID].microcms-management.io/api/v1/roles/[ロールID]'


2. Prepare the request body
Confirm that the retrieval was successful, then copy permissions from the response. Change defaultPermissions.billing.read to true, and save the updated permissions in role.json in the following format.

{
  "permissions": 取得して編集した権限設定
}

In the actual file, specify the entire retrieved permissions object, including any Custom Permissions you want to retain. Do not include other response properties such as id or isAdmin.

3. Update the role

curl -X PATCH 'https://[サービスID].microcms-management.io/api/v1/roles/[ロールID]' \
  -H 'X-MICROCMS-API-KEY: [APIキー]' \
  -H 'Content-Type: application/json' \
  -d @role.json

Response

Status Code

If the role is updated successfully, a 200 response is returned.
For status codes returned in case of an error, see "Error Response."

Response Body

If the role is updated successfully, a response like the following is returned.
The format is the same as the response for "GET /api/v1/roles/{role_id}."

{
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "name": "Content Editor (Updated)",
  "isAdmin": false,
  "permissions": {
    "defaultPermissions": { ... },
    "individualPermissions": [ ... ]
  },
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-02T00:00:00.000Z"
}

Error Response

The main errors returned by this API are as follows.

Status Code

Condition

400

When a role ID that is not in UUID format is specified (including UUIDs containing uppercase letters)

400

When neither name nor permissions is specified

400

When the request body is invalid (for example, only one of defaultPermissions and individualPermissions is specified, a required key is missing, a value is null, a type does not match, an undefined property is included, or an invalid value is specified for level)

400

When a nonexistent member, environment, or API is specified (including invited members and members or environments from other services)

403

When the Administrator role is specified

403

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

404

When a role that does not exist in the Service is specified

413

When the request body exceeds 1 MiB

You can check the error details in the message field of the response body.
For example, if neither name nor permissions is specified, the following response is returned.

{ "message": "Either \"name\" or \"permissions\" is required" }

For other errors, see Management API Error Responses.

Limitations

Roles That Cannot Be Updated

The Administrator role cannot be updated.

Use with Multiple Environments

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

Contents

  • Request Headers
  • X-MICROCMS-API-KEY
  • Content-Type
  • Path Parameters
  • role_id
  • Request Body
  • Request Examples
  • Updating only the role name
  • Changing part of the current permission settings
  • Response
  • Status Code
  • Response Body
  • Error Response
  • Limitations
  • Roles That Cannot Be Updated
  • Use with Multiple Environments
  • Company
  • Legal Notice
  • Terms of Service
  • Privacy Policy

Copyright © microcms.io All rights reserved.