microCMS

Tutorial
Next.js
Nuxt 3
Nuxt 2
Gatsby
Astro
Remix
JavaScript
PHP
Ruby
Go
iOS
Android
Manual
Account & Login
Services
Payment
API
Fields
Contents
Rich Editor
Reviews
Media
Permission Management
Connection
Logs
Security
Authentication
Specifications & Limitations
Content API
Basic Operations
API Keys
Responses & Error Handling
Management API (Beta)
Content Operations
Media Operations
Member Operations
API Operations
Service Operations
Responses & Error Handling
Image API
Parameters
MCP Server

Migration from the Old API (X-API-KEY, etc.)

Last updated: 2026/04/27
informationInformation

This section applies to services (API keys) created by October 22, 2021. Those who created services after that date do not need to perform any migration work.

This document explains the transition from the old format API keys (X-API-KEY, X-WRITE-API-KEY, X-DRAFT-API-KEY) to X-MICROCMS-API-KEY.

For more information about X-MICROCMS-API-KEY, please visit this page.

Transition to X-MICROCMS-API-KEY

Previously, it was necessary to use headers such as X-API-KEY to make requests.

// Normal data retrieval
$ curl "https://<subdomain>.microcms.io/api/v1/<endpoint>" \
    -H "X-API-KEY: <old API key>"

// Retrieving draft data
$ curl "https://<subdomain>.microcms.io/api/v1/<endpoint>" \
    -H "X-API-KEY: <old API key>" \
    -H "X-GLOBAL-DRAFT-KEY: <old API key>"

// Writing data
$ curl -X POST "https://<subdomain>.microcms.io/api/v1/<endpoint>" \
    -H "X-WRITE-API-KEY: <old API key>"

After the specification change, the API key has been unified under the X-MICROCMS-API-KEY header. By configuring the API key in the management screen, you can manage permissions related to draft retrieval and writing, allowing for a unified request header.
https://document.microcms.io/content-api/x-microcms-api-key

The method for specifying the API key after the transition is as follows.

$ curl "https://<subdomain>.microcms.io/api/v1/<endpoint>" \
    -H "X-MICROCMS-API-KEY: <old API key>"

If you are using an SDK, please update to the latest version and specify the API key as described in the Readme.

Automatic Migration of Existing API Keys

If you created X-API-KEY, X-WRITE-API-KEY, and X-DRAFT-API-KEY with the old format API keys, three types of X-MICROCMS-API-KEY have been generated for each.
The default permissions for each old API key are as follows.

  • X-API-KEY → GET only ON
  • X-WRITE-API-KEY → all OFF
  • X-GLOBAL-DRAFT-KEY → GET, only all draft retrieval ON
informationInformation
  • The GET permission for X-GLOBAL-DRAFT-KEY was additionally granted on February 20, 2023.
  • If you had configured HTTP methods, it has been migrated as individual permissions.

About the Migration Deadline

Currently, it is still possible to use the old headers such as X-API-KEY. However, we are considering phasing them out in the future, so please proceed with the migration as soon as possible.

Contents