コンテンツにスキップ
Docs
Esc
↑↓移動↵開く⌘Jプレビュー
このページの内容

認証

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 のエラーの一覧は エラー を見てください。

このページは役に立ちましたか?