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)

POST /api/v1/roles

Last updated: 2026/11/17

This is an API for creating a Role in a Service.

Information

This API is available on plans that support the Role feature (Business and Enterprise plans). An error is returned on plans that do not support the Role feature.

Request Headers

X-MICROCMS-API-KEY

This is the authentication key required for requests.
Enable "Create 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.

Request Body

Specify the role name and permissions for the role to be created.

Property

Type

Required

Description

name

string

Required

Role name. Specify between 1 and 100 characters. You can use the same name as an existing role.

permissions

object

Required

Role permission settings. Specify both defaultPermissions and individualPermissions. For details, see "permissions" below.

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

permissions

All keys in permissions must be specified. For permissions you do not use, specify false or NONE. If you omit a key or specify null or a value of a different type, a 400 response will be returned.

Tips

You can create a role with the same permission settings by sending the name and permissions from the response of the Role Details API (GET /api/v1/roles/{role_id}) as is. Use this when creating a role based on an existing role.

defaultPermissions

Default permissions.
Specify level as a string and memberIds and serviceIds as arrays of strings. Specify whether each operation is allowed or denied as a boolean.
For the meaning of each key and its corresponding item in the Role settings screen in the Administration console, see “GET /api/v1/roles/{role_id}” under “Permission details.”

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.
Example: members → read → level represents members.read.level, which is specified in the request body as follows.

"members": {
  "read": {
    "level": "ALL"
  }
}

Key

Type

Allowed values

members

read

level

string

ALL / SAME_ROLE / SPECIFIC / NONE

memberIds

array

An array of IDs for members who are allowed to view
Required when members.read.level is SPECIFIC. Cannot be specified otherwise.
An empty array ([]) is also allowed.

create

boolean

true / false

update

boolean

true / false

delete

boolean

true / false

roles

read

level

string

ALL / SAME_ROLE / NONE

create

boolean

true / false

update

boolean

true / false

delete

boolean

true / false

billing

read

boolean

true / false

update

boolean

true / false

apiKeys

read

boolean

true / false

usage

read

boolean

true / false

environments

read

level

string

ALL / URL_ONLY / RESTRICTED / NONE

serviceIds

array

An array of Service IDs for environments that are allowed to be viewed
Required when environments.read.level is RESTRICTED. Cannot be specified otherwise.
An empty array ([]) is also allowed.

create

boolean

true / false

delete

boolean

true / false

reviews

object

Specify all the same keys as in “GET /api/v1/roles/{role_id}” under “Details of reviews”

media

read

level

string

ALL / SAME_ROLE / CREATED / NONE

create

boolean

true / false

update

boolean

true / false

delete

boolean

true / false

api

read

boolean

true / false

create

boolean

true / false

update

boolean

true / false

delete

boolean

true / false

content

object

Specify all the same keys as in “GET /api/v1/roles/{role_id}” under “Details of content”

developerMenu

read

boolean

true / false

Notes for Each Key

  • Only the Administrator role has permission to update environments, so it cannot be specified.
  • For content.update, specify all 16 of the following items:
    • saveDraft, removeDraft, revertToDraftUnpublished, changeContentIdUnpublished, reorderUnpublished, changePublicationDateUnpublished, changeAuthor, changeDraftKey, publish, publishApproved, unpublish, unpublishApproved, revertToDraft, changeContentIdPublished, reorderPublished, changePublicationDatePublished

Values That Can Be Specified for level

Key

Available values

members.read.level

ALL / SAME_ROLE / SPECIFIC(※1) / NONE

roles.read.level

ALL / SAME_ROLE / NONE

environments.read.level

ALL / URL_ONLY / RESTRICTED(※2) / NONE

reviews.read.level

ALL / SAME_ROLE / CREATED / NONE

reviews.update.level

ALL / EDIT / NONE

Specify the members and environments allowed to view (※1, 2)

  • members.read.memberIds
    • Required when members.read.level is SPECIFIC. Omit members.read.memberIds otherwise.
    • Specify the IDs of the members allowed to view as an array. Duplicate IDs are not allowed. Only members who have joined the Service can be specified; invited members cannot be specified.
    • Member IDs can be found in the id field of the response from the API for retrieving the member list. An empty array ([]) can also be specified.
  • environments.read.serviceIds
    • Required when environments.read.level is RESTRICTED. Omit environments.read.serviceIds otherwise.
    • Specify the Service IDs of the environments allowed to view as an array. Duplicate IDs are not allowed. An environment's Service ID is the subdomain in its URL. Only environments belonging to this Service can be specified; the parent Service's own Service ID cannot be specified. An empty array ([]) can also be specified.

individualPermissions

An array of Custom Permissions for each API.
If you do not set any Custom Permissions, specify an empty array ([]).

Key

Type

Allowed values

apiId

string

The Endpoint name of the API for which to set Custom Permissions (e.g., blog). Specify the endpoint included in the response from the API list retrieval API.

The API name (Display Name) cannot be specified. Uppercase and lowercase letters are distinguished, and the same Endpoint cannot be specified more than once.

api

read

boolean

true / false

update

boolean

true / false

delete

boolean

true / false
api.create cannot be specified (API creation is not associated with a specific API)

content

object

Same format as defaultPermissions.content

developerMenu

read

boolean

true / false

reviews

object

Same format as defaultPermissions.reviews

Request Example

The following is an example of creating a “Content Editor” role that can edit and publish all content.

curl -X POST 'https://[サービスID].microcms-management.io/api/v1/roles' \
  -H 'X-MICROCMS-API-KEY: [APIキー]' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Content Editor",
    "permissions": {
      "defaultPermissions": {
        "roles": { "read": { "level": "NONE" }, "create": false, "update": false, "delete": false },
        "members": { "read": { "level": "NONE" }, "create": false, "update": false, "delete": false },
        "usage": { "read": false },
        "environments": { "read": { "level": "NONE" }, "create": false, "delete": false },
        "billing": { "read": false, "update": false },
        "apiKeys": { "read": false },
        "reviews": { "read": { "level": "ALL" }, "create": true, "update": { "level": "EDIT" } },
        "media": { "read": { "level": "ALL" }, "create": true, "update": true, "delete": false },
        "api": { "read": true, "create": false, "update": false, "delete": false },
        "content": {
          "read": { "level": "ALL" },
          "create": { "draft": true, "publish": true },
          "update": {
            "saveDraft": true,
            "removeDraft": true,
            "revertToDraftUnpublished": true,
            "changeContentIdUnpublished": true,
            "reorderUnpublished": true,
            "changePublicationDateUnpublished": true,
            "changeAuthor": true,
            "changeDraftKey": true,
            "publish": true,
            "publishApproved": true,
            "unpublish": true,
            "unpublishApproved": true,
            "revertToDraft": true,
            "changeContentIdPublished": true,
            "reorderPublished": true,
            "changePublicationDatePublished": true
          },
          "delete": true
        },
        "developerMenu": { "read": false }
      },
      "individualPermissions": []
    }
  }'

Example of a Role That Can View Only Specific Members and Environments

Change members and environments in the example above as follows.

"members": {
  "read": { "level": "SPECIFIC", "memberIds": ["[メンバーID]"] },
  "create": false,
  "update": false,
  "delete": false
},
"environments": {
  "read": { "level": "RESTRICTED", "serviceIds": ["[環境のサービスID]"] },
  "create": false,
  "delete": false
}

Example of Setting Custom Permissions for Each API

This example disables content and api in the default permissions, then sets permissions for a specific API (in this example, blog) using individualPermissions.

"individualPermissions": [
  {
    "apiId": "blog",
    "api": { "read": true, "update": false, "delete": false },
    "content": {
      "read": { "level": "ALL" },
      "create": { "draft": true, "publish": true },
      "update": {
        "saveDraft": true,
        "removeDraft": true,
        "revertToDraftUnpublished": true,
        "changeContentIdUnpublished": true,
        "reorderUnpublished": true,
        "changePublicationDateUnpublished": true,
        "changeAuthor": true,
        "changeDraftKey": true,
        "publish": true,
        "publishApproved": true,
        "unpublish": true,
        "unpublishApproved": true,
        "revertToDraft": true,
        "changeContentIdPublished": true,
        "reorderPublished": true,
        "changePublicationDatePublished": true
      },
      "delete": true
    },
    "developerMenu": { "read": false },
    "reviews": { "read": { "level": "ALL" }, "create": true, "update": { "level": "EDIT" } }
  }
]

Response

Status Code

If the Role is created successfully, a 201 response is returned.
For status codes returned in case of an error, see "Error Responses."

Response Body

If the Role is created 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": "コンテンツ編集者",
  "isAdmin": false,
  "permissions": {
    "defaultPermissions": { ... },
    "individualPermissions": []
  },
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z"
}

Error Responses

The main errors returned by this API are as follows.

Status Code

Condition

400

The request body is invalid (for example, a required key is missing, a value is null, a type mismatch, an undefined property, an invalid value for level, or name exceeds the character limit)

400

A nonexistent member, environment, or API is specified (including invited members and members or environments from other Services)

403

The Plan does not support the Role feature

403

The request targets an environment created using the Multiple Environments feature

413

The request body exceeds 1 MiB

You can check the error details in the message field of the response body.
For example, if content.update.publish is omitted, the following response is returned.

{ "message": "\"permissions.defaultPermissions.content.update.publish\" is required" }

For other errors, see Management API Error Responses.

Limitations

Roles That Cannot Be Created

Administrator roles cannot be created.

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
  • Request Body
  • permissions
  • Request Example
  • Example of a Role That Can View Only Specific Members and Environments
  • Example of Setting Custom Permissions for Each API
  • Response
  • Status Code
  • Response Body
  • Error Responses
  • Limitations
  • Roles That Cannot Be Created
  • Use with Multiple Environments
  • Company
  • Legal Notice
  • Terms of Service
  • Privacy Policy

Copyright © microcms.io All rights reserved.