認証
API キーと購入者の認証を使い分ける。
Cozeni の API には、API キーと購入者の Cookie の2種類の認証があります。API キーは管理操作に使い、購入者の Cookie は権利の確認に使います。API キーはサーバーの中だけで使い、ブラウザには渡しません。
API キー
API キーは次の形式で送ります。
GET https://api.cozeni.net/external/v1/account
Authorization: Bearer cozeni_sk_…
- 本番のキーは
cozeni_sk_で始まり、その後に64桁の16進数が続きます。 - サンドボックスのキーは
cozeni_sk_sandbox_で始まります。 - キーは管理画面の「開発者設定」で発行します。CLI の
loginでも CLI 用のキーを取得できます。 - 有効期限は7日、30日、90日、または期限なしから選びます。既定は7日です。
- 管理画面で発行した有効なキーは20本までです。CLI のキーはこの本数に含めません。
- CLI のキーは有効期限が30日に決まっています。有効な CLI のキーは5本までで、すでに5本あるときは、いちばん古いキーを失効させてから新しいキーを発行します。
- 秘密の値は発行したときに1回だけ表示されます。紛失したら、一覧から失効させて再発行します。
- キーを失効させても、購入者の Cookie や購入リンクは失効しません。
管理画面で「APIキーを発行」を押し、「名称」(前後の空白を除いて1〜100文字)を入力します。「権限」は1つ以上選びます。最初は導入用の4権限が選ばれており、「導入用の4権限を選ぶ」でも選び直せます。
一覧では名称・権限、状態(有効・期限切れ・失効済み)と環境、作成日・有効期限・最終利用を確認できます。キーは一部を伏せて表示され、末尾4桁と CLI で発行したかどうかも分かります。有効なキーは一覧の「失効」から失効させられます。
スコープ
API キーにはスコープ(操作の範囲)を付けます。write のスコープは対応する read を含みません。読み取りも必要なら、両方を付けます。
| スコープ | 操作できる範囲 |
|---|---|
products:read |
商品の一覧と取得です。 |
products:write |
商品の作成、更新、画像の設定と削除です。サンドボックスでは、テスト購入と返金も含みます。 |
checkout_links:read |
購入リンクの取得です。 |
checkout_links:write |
購入リンクの発行です。 |
checkouts:write |
購入画面の作成です。 |
customers:read |
機能フラグの照会です。 |
GET /account はスコープに関係なく、有効なキーで呼べます。
購入画面の作成や機能フラグの照会に使い続けるキーは、有効期限に「期限なし」か「90日」を選びます。期限を設定した場合は切れる前に新しいキーへ差し替えてください。期限が切れると、購入画面の作成や機能フラグの照会が止まります。
購入者の認証
お客様は Cozeni のアカウントを持ちません。購入時のメールアドレスに届くコードで入場します。入場が済むと、サイトのサーバーが購入者の Cookie を設定し、以後の権利の確認に使います。
- Cookie の名前は
cozeni_customerです。 - 属性は HttpOnly、SameSite=Lax、Path=/ です。HTTPS では Secure が付きます。有効期限は7日です。
- サイトのサーバーはこの Cookie だけを Cozeni に転送します。ほかの認証の Cookie は転送しません。
- この Cookie はサイトのドメインに保存されます。HttpOnly のため、ブラウザの JavaScript からは読めません。
購入の後、Cozeni はサイトの URL に cozeni_code を付けて戻します。サイトはこのコードを交換して、購入者の Cookie を作ります。コードは60秒で失効し、1回しか使えません。
安全に扱う
- API キーはサーバーの環境変数だけに置きます。
NEXT_PUBLIC_で始まる変数には置かないでください。ブラウザに送られるコードや画面にも含めないでください。 - API キーをリポジトリ、ログ、URL に出さないでください。
cozeni_codeは URL に付くため、アクセスログに残さないでください。- 権利をページ、Route Handler、Server Action のそれぞれで確認してください。レイアウトだけで隠すと、直接呼ばれたときに使えてしまいます。
API のエラーの一覧は エラー を見てください。