microCMS

チュートリアル
操作マニュアル
コンテンツAPI
マネジメントAPI（ベータ）
画像API

APIキー（X-MICROCMS-API-KEY）

最終更新日:2023年07月24日

X-MICROCMS-API-KEYは各APIリクエスト(GET、POST、PUT、PATCH、DELETE)の際に必要な認証キーです。
APIキーを作成し、リクエストヘッダーに含めて送信してください。
旧APIキー形式からの移行については旧API（X-API-KEYなど）からの移行をご覧ください。

設定方法

サイドバーの「○個のAPIキー」をクリックしてAPIキー一覧画面に遷移することができます。



APIキー管理一覧の「追加」ボタンをクリックして、APIキーを作成できます。
また各APIキーをクリックすることで、詳細画面で編集できます。



APIキーの作成画面は以下のようになります。
APIキーの権限はサービス全体のAPIキーの権限を設定する「①デフォルト権限」と各APIごとに個別の権限を設定する「②個別権限」があります(詳細は後述)。
それぞれ、必要なメソッドの権限を設定してAPIキーを作成してください。



「+ 個別権限を追加」をクリックすると、各APIを選択してAPIごとに追加できます。


権限設定

APIキーの権限設定には「デフォルト権限」と「個別権限」があります。

デフォルト権限

サービス全てのAPIのデフォルト権限を設定できます。
設定できるメソッドは「GET」「下書き全取得」「POST」「PUT」「PATCH」「DELETE」です。
デフォルト権限はサービス全体の全てのAPIに適用されます。

下書きの全取得

「下書きの全取得」は全ての下書き状態のコンテンツを一度に取得する際に利用する権限です。
一覧の表示など、複数の下書きコンテンツを同時に取得する必要がある場合に設定をしてください。（単一の下書き状態のコンテンツを取得する際は、コンテンツ毎に生成されたdraftKeyを使用します。）

informationInformation
  • 下書きの全取得を設定する際は、同時に「GET」権限を付与することが必要ですので、ご注意ください。
  • 公開中かつ下書き中のコンテンツに対して、下書きの全取得の権限が付与されたAPIキーでアクセスする際は、以下の仕様にご注意ください。
「公開中かつ下書き中」のステータスのコンテンツにおいて、filtersおよびqパラメータで下書き中の値を検索しても取得できません
https://help.microcms.io/ja/knowledge/public-and-draft-content-filtering

個別権限

API単位で個別に権限を設定できます。指定したAPIに関してはデフォルト権限が上書きされます。
例えば、デフォルト権限で「GET」を指定し、個別権限設定で「POST」「PUT」権限を付与した場合、該当のAPIには「POST」「PUT」の権限が付与されることになります。この例のようにAPIの個別権限では、GETの権限が打ち消されます。
設定できるメソッドはデフォルト権限と同じく「GET」「下書き全取得」「POST」「PUT」「PATCH」「DELETE」です。

informationInformation

クライアントサイドから直接APIを呼び出すことでユーザーがAPIキーを把握できてしまう場合、エンドポイントさえ分かればAPIを呼び出せてしまうことにご注意ください。
特に書き込み権限が付与されたAPIキー(POST、PUT、PATCH、DELETE)や下書きの全取得の権限が付与されたAPIキーの漏洩にご注意ください。
対処法としては、サーバサイドからAPIを呼び出す、またはJamstack構成にするなどしてキーを漏洩しないことが挙げられます。

ユースケース

X-MICROCM-API-KEYの権限管理を活用いただくことで、要件に応じて権限を設定することができます。各プロダクト・プランに応じて適切な権限設定を行ってください。

ユースケース１（より安全に書き込み系のAPIキーを使用する）

書き込み系のメソッド(POST、PUT、PATCH、DELETE)の権限が付与されたAPIキーが漏洩等してしまった場合、コンテンツを不正に書き換えられる等のリスクがあります。ですので、書き込み系のメソッドが付与されたAPIキーを取り扱う際は特に注意が必要です。
読み取りメソッド(GET)と書き込み系のメソッドの権限を分け、管理することでより安全にかつ柔軟にAPIキーを活用することができます。
以下のような設定・運用が考えられるでしょう。

  • デフォルト権限ではGETのみを許可する。

  • お問い合わせなどの更新がされるコンテンツAPIのみPOSTなどの書き込み系の個別権限を設定する。このAPIキーはサーバーサイドで処理するなど取り扱いには注意をする。


ユースケース２（公開・非公開コンテンツで使い分ける）

基本的に全てのコンテンツをユーザに公開するが、一部のAPIだけはユーザには見せず社内でのみ使いたいというようにコンテンツに応じて公開・非公開を分けたいケースがあるかと思います。
このようなケースでは、

  • デフォルト権限は全て false

  • 公開する API は個別権限で GET のみ true

  • プライベートな API は個別権限なし


という設定でキーを作ると、そのキーを直接クライアントに埋め込むことができるので API キーを隠すための中間サーバを作る手間を省くことができます。

ユースケース３（マルチデバイスごとの設定）

マルチデバイスに展開をしている場合、「ウェブサイト用」「iOS用」「Android用」のように同じ権限でAPIキーを複数作成することができます。
これによりチームやデバイス毎に更新サイクルのコントロールやアクセス範囲の調整ができます。

その他にも「ランキング処理を行うバッチ処理用」や「ローカルでのデータを簡単に確認するための最低限の読み取り用」など、開発をスムーズかつ安全に進めるための様々な用途が考えられます。

料金

プランによって、作成できるAPIキーの数が異なります。詳しくは料金表をご覧ください。

SDK