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
  • Content API

API Key (API Authentication and Authorization Management)

Last updated: 2026/11/20

X-MICROCMS-API-KEY is the authentication key required for each API request (GET, POST, PUT, PATCH, DELETE). Please include the X-MICROCMS-API-KEY in the request header when sending.
API keys can be created, edited, and deleted only by users with administrator privileges.

For information on migrating from the old API key format, please see Migration from the old API (such as X-API-KEY).

Information

The number of API Keys you can create varies by Plan. For details, see the Pricing Plans page.

Danger

Depending on the permission settings of the API key, it may be possible to write from external sources (WRITE API requests), which could lead to draft content being published. Please handle it with care.

In particular, in a configuration where the API is called directly from the client (CSR), external users can obtain the API key. In such cases, if they know the endpoint, they can call any API, so please be cautious.
Possible countermeasures include the following methods:

  • Grant only the minimum necessary GET permissions (to ensure that the API key can be exposed without issues)
  • Call the API from the server side to keep the API key confidential (to prevent exposure of the API key)

What is an API Key?

An API key is a type of authentication key used for authentication and access control when using an API. It is primarily used to verify whether the user utilizing the API has the appropriate access rights. In microCMS, an API key called X-MICROCMS-API-KEY is provided for authentication and other purposes.

How to Create an API Key

First, click on "○ API Keys" in the sidebar to navigate to the API key list screen.



Clicking the "Add" button in the API key management list will display the API key creation modal, allowing you to create an API key.



You will set the API key name and configure the permissions granted to the API key in detail.



There are two main items in the API key settings. You can switch tabs within the modal screen, so please make the necessary settings according to your needs.

  • Content API
  • Management API (Beta)

Content API Settings

There are two types of permissions for Content API settings:

  • “1. Default Permissions” to set permissions for the entire service's API key
  • “2. Individual Permissions” to set individual permissions for each API

Below, we will explain each type of permission.

1. Default Permissions



You can set the default permissions for all APIs of the service.
Default permissions apply to all APIs across the entire service.

The items that can be set are as follows:

  1. GET
  2. Retrieve all draft content
  3. Retrieve all expired content
  4. POST
  5. PUT
  6. PATCH
  7. DELETE

Retrieve All Draft Content

The “Retrieve All Draft Content” permission is used when retrieving multiple draft contents. Please use it when you want to check the display of a list in draft status.
(To retrieve a single draft content, use draftKey.)

Retrieve All Expired Content
The “Retrieve All Expired Content” permission is used when retrieving multiple expired contents. Please use it when you need to retrieve expired content for purposes such as backup.

Warning

When setting up the retrieval of all draft content and the retrieval of all published content, it is necessary to grant "GET" permissions simultaneously.

Warning

In the case of content that is "published and in draft," even if the permission for "retrieve all draft content" is granted, it is designed to only search for published data. For more details, please refer to this help article.


2. Individual Permissions



You can set individual permissions for each API.
The specified API will override the default permissions.

For example, if you specify "GET" as the default permission and grant "POST" and "PUT" permissions in the individual permission settings, the corresponding API will have "POST" and "PUT" permissions granted.

The items that can be set are the same as the default permissions.

By clicking on “+ Add Individual Permissions,” you can add individual permissions for multiple APIs.

Management API (Beta) Settings

For the Management API, which is available in beta, you can enable an operation by checking the box next to it.
Open the “Management API (Beta)” tab in the API Key creation modal and configure the settings.



For details about each Management API Endpoint, see the page below.

What is the Management API?
https://document.microcms.io/en/management-api/introduction

Use Cases for Configuring Permissions with API Keys

X-MICROCMS-API-KEY permissions let you configure access according to your requirements. Set appropriate permissions based on how you plan to use the API key.

1. Use Write API Keys More Securely

If an API key with permissions for write methods (POST, PUT, PATCH, DELETE) is leaked, there is a risk that Content could be modified without authorization. Therefore, take particular care when handling API keys with permissions for write methods.
Separating and managing permissions for read methods (GET) and write methods lets you use API keys more securely and flexibly.
Consider the following configuration and usage practices:

  • Allow only GET in the default permissions.
  • Set individual permissions for write methods such as POST only for Content APIs that are updated, such as those used for inquiries. Handle this API key with care, for example, by using it only for server-side processing.


2. Use Different Permissions for Public and Private Content

You may want to make all Content available to users by default, while keeping certain APIs hidden from users and using them only internally. In such cases, you can configure permissions separately for public and private Content as follows:

  • Set all default permissions to false.
  • For APIs you want to make public, set only GET to true in the individual permissions.
  • Do not set individual permissions for private APIs.


Creating a key with these settings lets you embed it directly in the client, eliminating the need to build an intermediary server to hide the API key.

3. Configure Keys for Different Devices

If you support multiple devices, you can create multiple API keys with the same permissions, such as one for your website, one for iOS, and one for Android.
This lets you control update cycles and adjust access scopes for each team or device.

Other possible uses include a key for batch processing that handles rankings, or a key with minimal read permissions for easily checking data locally. There are many ways to streamline and secure development.

Contents

  • What is an API Key?
  • How to Create an API Key
  • Content API Settings
  • Management API (Beta) Settings
  • Use Cases for Configuring Permissions with API Keys
  • 1. Use Write API Keys More Securely
  • 2. Use Different Permissions for Public and Private Content
  • 3. Configure Keys for Different Devices
  • Company
  • Legal Notice
  • Terms of Service
  • Privacy Policy

Copyright © microcms.io All rights reserved.