API キーを作る、権限を決める
API キーは、Content API を使うための鍵です。キーごとに、何をしてよいか（権限）を決められます。このページでは、キーを発行し、権限を決め、要らなくなったキーを止めるまでを説明します。
- スペースで API キーを管理できるロールが要ります。初めからあるロールでは、［オーナー］と［管理者］です
- API キーは、スペースごとに発行します。キーで呼べるのは、そのキーのスペースのエントリーとメディアだけです
API キーを発行する
Section titled “API キーを発行する”API キーを発行するには、次のようにします。
- 管理画面の左のメニューで、［API キー］を押します。
- ［名前］に、キーを見分けるための名前を入れます（例：「本番サイト」）。名前は 1〜100 文字です。
- ［発行］を押します。
「API キーを発行しました。このキーは今しか表示されません。安全な場所に控えてください」と表示され、hako_ で始まるキーが表示されます。
キーはこのときに 1 度だけ表示されます。 Hako CMS にはキーそのものは残りません。なくしたときは、新しいキーを発行してください。
発行したばかりのキーの権限は［読み取り］だけです。公開中のエントリーを読むことだけができます。
権限を決める
Section titled “権限を決める”権限は、エントリーの操作ごとに決めます。
| 権限 | できること |
|---|---|
| 読み取り | 公開中のエントリーを読む |
| プレビュー | preview=true を付けて、下書きも読む。［読み取り］も要る |
| 作成 | エントリーを作る。作ったエントリーは下書きになる |
| 更新 | 下書きを変える、捨てる |
| 公開 | 公開する、公開をやめる、公開の日時を予約する |
| 削除 | エントリーを削除する |
権限を変えるには、次のようにします。
- ［API キー］の画面で、権限を変えたいキーの名前を押します。
- ［権限］の表の［既定（すべてのコンテンツタイプ）］の行で、許す操作にチェックを入れます。
- （省略可）コンテンツタイプごとに変えたいときは、そのコンテンツタイプの行の［個別に設定］にチェックを入れ、許す操作にチェックを入れます。
- （省略可）メディアの API を使うときは、［メディア］で［読み取り］［アップロード］［編集］［削除］のうち、許す操作にチェックを入れます。
- ［保存］を押します。
「保存しました」と表示されます。変えた権限は、次のリクエストからすぐに効きます。
［個別に設定］にチェックを入れたコンテンツタイプでは、既定の権限は使われず、個別の権限だけで決まります。既定の権限と足し合わせることはありません。たとえば、既定で［読み取り］を許していても、個別の権限で［読み取り］を外したコンテンツタイプは読めません。
メディアの権限は、エントリーの権限とは別に決めます。
ブラウザに渡してよいキー
Section titled “ブラウザに渡してよいキー”API キーをブラウザで動くコードに入れると、サイトを見た人が誰でもキーを見られます。
- ［読み取り］だけのキーは、ブラウザに渡してもかまいません。公開中のエントリーは、もともと誰に見せてもよいものだからです
- ［プレビュー］や、書き込み（［作成］［更新］［公開］［削除］）、メディアの権限を持つキーは、ブラウザに渡さないでください。 サイトのサーバーの中だけで使います
公開中のページと、下書きのプレビューや書き込みとで、キーを分けると安全です。
キーを止める、もとに戻す
Section titled “キーを止める、もとに戻す”キーが漏れたときや、使わなくなったときは、キーを失効させます。
- ［API キー］の画面で、止めたいキーの行の［失効］を押します。
- 確かめの画面で、もう一度［失効］を押します。
キーはすぐに使えなくなります。そのキーで呼ぶと 401 が返ります。失効したキーは［失効したキー］の一覧に移ります。
止めたキーをもう一度使うときは、［失効したキー］の一覧で、そのキーの［再び有効にする］を押し、確かめの画面でもう一度［再び有効にする］を押します。同じキーが、失効したときの権限のまま、また使えるようになります。キーが漏れたために止めたときは、再び有効にせず、新しいキーを発行してください。
発行したキーで、公開中のエントリーを取り出してみます。<ホスト名> はあなたの環境のホスト名、<コンテンツタイプ ID> はコンテンツタイプの［エンドポイント］の値、<API キー> は発行したキーに置き換えてください。
curl https://<ホスト名>.hakocms.net/api/v1/content/<コンテンツタイプ ID> \ -H "Authorization: Bearer <API キー>"items と total を持つ JSON が返れば、キーは使えています。401 が返るときは、キーが違うか、失効しています。403 が返るときは、キーにその操作の権限がありません。