---
title: "API キー"
description: "API リクエストを認証し、キーを安全に管理します。"
source: "https://docs.tokenz.one/ja/v2/checkout/api-keys"
api_version: "v2"
locale: "ja"
version_status: "current"
docs_stage: "prod"
---

# API キー

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

## はじめに

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

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

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

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

## テストキーとライブキー

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

| プレフィックス | モード | 送金 |
| --- | --- | --- |
| `secret_test_…` | テスト | なし（支払いはシミュレーションのみ） |
| `secret_live_…` | ライブ | あり（実際の支払い） |

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

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

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

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

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

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

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

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

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

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

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

## Webhook の署名シークレット

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

署名の検証方法については [Webhook](https://docs.tokenz.one/ja/v2/checkout/webhooks-get-started) を参照してください。