APIキー（APIの認証と権限管理）
X-MICROCMS-API-KEY は各APIリクエスト（GET、POST、PUT、PATCH、DELETE）の際に必要な認証キーです。X-MICROCMS-API-KEY をリクエストヘッダーに含めて送信してください。
APIキーは管理者権限を持つユーザーのみ、作成／編集／削除が可能です。
旧APIキー形式からの移行については旧API（X-API-KEYなど）からの移行をご覧ください。
InformationAPIキーはプランごとに作成できる個数が異なります（Hobbyプランで1個、Teamプランで3個、Businessプランで10個、Advancedプランで20個）。
プランごとに利用できる機能については、料金プランページをご覧ください。
CautionAPIキーの権限設定によっては、外部からの書き込み（WRITE系APIのリクエスト）が可能になったり、下書き状態のコンテンツが公開状態になってしまう可能性がございます。お取り扱いにはご注意ください。
特にクライアントから直接APIを呼び出す構成（CSR）の場合、外部のユーザーがAPIキーを把握することができます。その場合、エンドポイントさえ分かれば、任意のAPIを呼び出せてしまうため、ご注意ください。
対策としては、以下のような方法が考えられます。- 必要最低限のGET権限を付与する（APIキーが露出しても問題ない状態にする）
- サーバーサイドからAPIを呼び出し、APIキーを秘匿する（APIキーの露出を防ぐ）
APIキーとは？
APIキーとは、APIを使用する際に認証やアクセス制御を行うための一種の認証キーです。主に、APIを利用するユーザーが適切なアクセス権を持っているかの認証に用いられます。microCMSでは、X-MICROCMS-API-KEYというAPIキーを提供し認証などを行っています。
APIキーの作成方法
まず、サイドバーの「○個のAPIキー」をクリックしてAPIキー一覧画面に遷移します。
APIキー管理一覧の「追加」ボタンをクリックすると、APIキー作成モーダル画面が表示され、APIキーを作成できます。
APIキー名の設定と、APIキーに付与する権限について詳細設定を行います。
APIキーの設定には大きく以下の2つの項目があります。モーダル画面内でタブ切り替えができますので、それぞれ用途に応じて必要な設定をしてください。
- コンテンツAPI
- マネジメントAPI（ベータ）
コンテンツAPIの設定
コンテンツAPI設定の権限には、以下の2つの種類があります。
- サービス全体のAPIキーの権限を設定する「1. デフォルト権限」
- 各APIごとに個別の権限を設定する「2. 個別権限」
以下、それぞれの権限について解説します。
1. デフォルト権限
サービス全てのAPIのデフォルト権限を設定できます。
デフォルト権限はサービス全体の全てのAPIに適用されます。
設定できる項目は、以下の通りです。
- GET
- 下書きコンテンツの全取得
- 公開終了コンテンツの全取得
- POST
- PUT
- PATCH
- DELETE
下書きコンテンツの全取得
「下書きコンテンツの全取得」は、複数の下書きコンテンツを取得する場合に利用する権限です。下書き状態で一覧の表示を確認されたい場合などに、ご利用ください。
（単一の下書きコンテンツを取得する際は、draftKeyを使用します。）
公開終了コンテンツの全取得
「公開終了コンテンツの全取得」は、複数の公開終了コンテンツを取得する場合に利用する権限です。バックアップなどの用途で、公開終了コンテンツの取得が必要な場合にご利用ください。
- Information
下書きコンテンツの全取得、公開終了コンテンツの全取得を設定する際は、同時に「GET」権限を付与することが必要です。
- Caution
「公開中かつ下書き中」のコンテンツにおいては、「下書きコンテンツの全取得」の権限が付与されていても、公開中のデータのみを対象に検索される仕様となっています。詳細はこちらのヘルプ記事をご覧ください。
2. 個別権限
API単位で個別に権限を設定できます。
指定したAPIに関してはデフォルト権限に対して上書きされます。
例えば、デフォルト権限で「GET」を指定し、個別権限設定で「POST」「PUT」権限を付与した場合、該当のAPIには「POST」「PUT」の権限が付与されることになります。
設定できる項目は、デフォルト権限と同じです。
「+ 個別権限を追加」をクリックすることで、複数のAPIに対して個別権限を追加できます。
マネジメントAPI（ベータ）の設定
ベータ版として提供しているマネジメントAPIについては、利用したい操作項目にチェックを入れることで当該操作が可能となります。
APIキー作成モーダルの「マネジメントAPI（ベータ）」のタブを開き、設定してください。
それぞれの項目の詳細については、下記のリンクからご確認ください。
APIキーによる権限設定のユースケース
X-MICROCMS-API-KEYの権限管理を活用いただくことで、要件に応じて権限を設定することができます。運用方法に応じて適切な権限設定を行ってください。
1. より安全に書き込み系のAPIキーを使用する
書き込み系のメソッド(POST、PUT、PATCH、DELETE)の権限が付与されたAPIキーが漏洩等してしまった場合、コンテンツを不正に書き換えられる等のリスクがあります。ですので、書き込み系のメソッドが付与されたAPIキーを取り扱う際は特に注意が必要です。
読み取りメソッド(GET)と書き込み系のメソッドの権限を分け、管理することでより安全にかつ柔軟にAPIキーを活用することができます。
以下のような設定・運用が考えられるでしょう。
- デフォルト権限ではGETのみを許可する。
- お問い合わせなどの更新がされるコンテンツAPIのみPOSTなどの書き込み系の個別権限を設定する。このAPIキーはサーバーサイドで処理するなど取り扱いには注意をする。
２. 公開・非公開コンテンツで使い分ける
基本的に全てのコンテンツをユーザに公開するが、一部のAPIだけはユーザには見せず社内でのみ使いたいというようにコンテンツに応じて公開・非公開を分けたいケースがあるかと思います。
このようなケースでは、
- デフォルト権限は全て false
- 公開する API は個別権限で GET のみ true
- プライベートな API は個別権限なし
という設定でキーを作ると、そのキーを直接クライアントに埋め込むことができるので API キーを隠すための中間サーバを作る手間を省くことができます。
３. マルチデバイスごとの設定
マルチデバイスに展開をしている場合、「ウェブサイト用」「iOS用」「Android用」のように同じ権限でAPIキーを複数作成することができます。
これによりチームやデバイス毎に更新サイクルのコントロールやアクセス範囲の調整ができます。
その他にも「ランキング処理を行うバッチ処理用」や「ローカルでのデータを簡単に確認するための最低限の読み取り用」など、開発をスムーズかつ安全に進めるための様々な用途が考えられます。