API キー
用途ごとに 1 つのキー、それ以上は持たせない。
サービスごとに専用のキーを発行し、必要なスコープと送信元だけを持たせます。すべての呼び出しが記録されます。
概要
API キーとは?
コードがリクエストのたびに送るシークレットです。どのワークスペース向けの呼び出しか、何をしてよいかを示します。
32
選べるスコープ
25
1 つの送信範囲に入れられるドメイン
3,650
日、最長の有効期限
仕組み
ロールを上限にする
ロールを付けると、キーはそのロールが許す以上のことはできません。GET /ping で、キーが指定した範囲とロールが残した範囲を確認できます。
送信元を制限する
ドメイン単位で最大 25 件、アドレス単位で最大 50 件。範囲外の送信元は 403 になります。
すべての呼び出しを記録
リクエストごとのメソッド、パス、ステータス、エラー、所要時間に加え、よく使われるルートとその失敗率。
キーでできることを確認する
GET /ping はスコープ不要で、キーの権限範囲を返します。
{ "ok": true, "keyId": "4c1b257a66287fd113bd89d0", "mode": "live", "scopes": ["emails:send", "templates:write", "members:write"], "roleId": "role_2b81de079c1f0a4b7e05d386", "grantedScopes": ["emails:send", "templates:write"], "workspaceId": "10417196-e324-4283-af98-66ec62167c47"}できること
いま使える機能
そのままローテーション
ID、スコープ、履歴はそのままで、シークレットだけが新しくなります。
削除ではなく失効
以降の呼び出しには revoked_api_key が返ります。
有効期限を内蔵
最長 10 年先まで、キーの期限を設定できます。
上手な使い方
使いこなすために
- 01
サービスごとに 1 キー
漏えいしても影響は 1 つの連携だけで済みます。
- 02
最小限だけ与える
emails:send から始め、呼び出しに必要になったらスコープを足します。
- 03
失敗を見張る
デプロイ後は、リクエストログを失敗した呼び出しで絞り込みます。
現状
知っておきたいこと
- IP 許可リストなし
- キーをサーバーのアドレスに結び付けることはまだできません。
- テスト用キーなし
- 作成できるのは oe_live_ キーだけなので、送信はすべて本物です。
- API からのログ取得なし
- リクエストログはアプリで閲覧し、REST ルートでは取得できません。
質問
よくある質問
さらに見る
