Definition
パスポートAPIにはどう認証しますか。
貴社のシステムは、環境ごと・機能ごとに発行されたスコープ付きのベアラーキーを HTTPS 上で提示します。制限付きのパスポート階層を読む第三者は鍵をまったく使いません。アクセスポリシーが信頼する当事者が発行した W3C 検証可能クレデンシャルを提示し、リゾルバーはそのクレデンシャルが認める階層を返します。
The separation matters because the two have different lifecycles. A key belongs to your integration and rotates on your schedule; a credential belongs to a recycler or an authority and is revoked when their permit lapses, not when your contract does.
リクエスト
キーを提示する
curl https://api.circuleid.com/v1/passports/01/09506000134352 \
-H "Authorization: Bearer $CIRCULEID_API_KEY"
# Scope errors are explicit rather than a bare 403:
# {
# "error": "insufficient_scope",
# "required": "passports:read:restricted",
# "granted": ["passports:read:public", "events:write"]
# }比較
キーとクレデンシャルの比較
| API key | Verifiable credential | |
|---|---|---|
| Authenticates | Your systems | A third party reading a passport |
| Issued by | CirculeID, to your organisation | A party the access policy trusts |
| Scoped by | Environment and capability | What the credential asserts |
| Revoked when | You rotate or a key leaks | A permit or accreditation lapses |
| Verified by | Us, on each request | Anyone, cryptographically |
| Lives in | Your secret manager | The holder’s own wallet or system |
実務
当社の推奨
サービスごとに一つの鍵
そうすれば、漏えいの影響範囲を一文で説明できます。
最小権限のスコープ
発行パイプラインが制限付き階層への読み取り権限を必要とすることはありません。
環境の分離
サンドボックスのキーは、設計上、本番のパスポートに到達できません。
重複期間を設けたローテーション
切り替え期間中は両方の鍵が有効なので、鍵のローテーションがデプロイ競争になりません。
可能な限り短命に
一時的なワークロードが使う鍵に有効期限を設けることで、漏えいが問題であり続ける期間を限定します。
前提を置く前に検証する
ログは、鍵が有効であった間に何を行ったかを示します。影響範囲を判断する根拠となります。
回答
よくある質問
ここでいう API キーとクレデンシャルの違いは何ですか。
APIキーは貴社システムをCirculeIDに対して認証し、貴社組織が実行できる範囲に限定されます。検証可能クレデンシャルは第三者 — リサイクル事業者、修理事業者、当局 — をパスポートに対して認証し、どの階層を受け取るかを決めます。キーは当社が発行し、クレデンシャルはアクセス方針が信頼する主体から発行されます。
キーのスコープはどう設定すべきですか。
狭く、サービスごとにです。発行パイプラインに必要なのはパスポートへの書き込み権限だけであり、店舗フロントに必要なのは公開階層の読み取り権限だけです。機能ごとに限定していれば、あるサービスの鍵が漏れても、別のサービスが持つ制限付きデータは露出しません。
サンドボックスと本番のキーは相互に使えますか。
いいえ。意図的にそうしています。キーは環境情報を保持するため、サンドボックスのキーが本番のパスポートに触れることはなく、本番のキーが誤ってテスト環境で使われることもありません。パスポートは長期に残る公開成果物です。本番での誤発行は、こっそり削除できるものではありません。
鍵のローテーションはどう扱われますか。
キーは重ねられます。新しいキーを発行し、展開してから、古いキーを失効させます。その間は両方が有効です。重複期間のないローテーションはデプロイ競争になり、その結果、組織は結局一度もローテーションしなくなります。
鍵が漏えいした場合はどうなりますか。
直ちに失効させてください。失効はキャッシュの期限切れではなく、次のリクエストから効きます。監査ログには、そのキーが有効だった間に何をしたかが残ります。影響範囲を判断するのに必要なのはそれであり、キーを狭く限定しておくとその判断が短く済む理由でもあります。