API キー

API リクエストを認証し、キーを安全に管理します。

はじめに

Tokenz API へのすべてのリクエストは、シークレット API キーをベアラートークンとして送信することで認証されます。

curl https://api.tokenz.one/v2/checkoutsession \
  --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE'

Tokenz が使用するのはシークレットキーのみです。公開可能な（publishable）クライアント側のキーは存在しません。シークレットキーはアカウントに対して決済の作成や注文データの参照ができるため、サーバーの外に出してはいけません。

キーの作成と管理は、ダッシュボードの Developers → API keys で行います。

テストキーとライブキー

各キーはいずれか一方のモードに属します。

連携の構築とテストにはテストキーを使用し、本番環境ではライブキーに切り替えます。テストキーで実際の支払いを処理することはできず、ライブキーをテストモードで使用することもできません。そのため、両者は環境ごとに分けて管理してください（例：環境ごとに値が異なる TOKENZ_SECRET_KEY 変数）。

シークレットキーを秘密に保つ

クライアント側で安全に使えるキーは存在しないため、シークレットキーはパスワードと同じように扱ってください。

• サーバー側でのみ使用します。 ブラウザのコード、モバイルアプリ、SPA のバンドルなど、ユーザーの端末に配布されるものには決して含めないでください。
• ソース管理にコミットしないでください。また、ログ、エラーメッセージ、URL にも含めないでください。
• 環境変数またはシークレットマネージャーに保存し、コードベースには置かないでください。

キーは作成時に一度だけ表示されます。その場でコピーして安全に保管してください。紛失した場合は、復元しようとせず、新しいキーを作成してください。

必要なスコープのみを付与する

キーを作成する際に、その**権限（スコープ）**を選択します。たとえば、Checkout Session の作成／参照、注文の参照／キャンセル、配送記録、商品の参照、返金の作成／参照、リデンプションコードの検証／利用、サブスクリプションのプラン変更などです。

各キーには必要最小限の権限のみを付与してください。

• 連携やサービスごとに個別のキーを使用し、その連携が使うスコープだけを付与します。注文を参照するだけのレポート処理に、返金やチェックアウトの権限は必要ありません。
• スコープを絞ったキーが漏洩しても影響範囲は小さく、他に影響を与えずにそのキーだけを失効させられます。

キーのローテーションと失効

• ローテーションは、新しいキーを作成してデプロイし、その後 Developers → API keys で古いキーを削除します。複数のキーを同時に保持できるため、ダウンタイムなしで切り替えられます。
• キーが漏洩した場合（リポジトリへのコミット、チケットへの貼り付け、ログ出力など）は、直ちに削除してください。キーを削除すると失効し、そのキーを使用したリクエストは動作しなくなります。その後、新しいキーを発行してください。

Webhook の署名シークレット

Webhook エンドポイントの署名シークレットは、API キーとは別のものです。Tokenz は各 Webhook をこのシークレットで署名し、あなたは Tokenz-Signature ヘッダーを生のリクエストボディに対して検証することで、イベントが正当であることを確認します。署名シークレットも API キーと同様にサーバー側で保管してください。

署名の検証方法については Webhook を参照してください。