---
title: 認証
description: API キーと購入者の認証を使い分ける。
---

Cozeni の API には、API キーと購入者の Cookie の2種類の認証があります。API キーは管理操作に使い、購入者の Cookie は権利の確認に使います。API キーはサーバーの中だけで使い、ブラウザには渡しません。

## API キー

API キーは次の形式で送ります。

```http
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` はスコープに関係なく、有効なキーで呼べます。

:::note
導入プロンプトと CLI が取得するキーには、最初の4つのスコープ（`products:read`、`products:write`、`checkout_links:read`、`checkout_links:write`）が付きます。機能フラグを使うサイトでは、`checkouts:write` と `customers:read` の2つのスコープを付けたキーを発行して、サーバーの環境変数に置きます。
:::

購入画面の作成や機能フラグの照会に使い続けるキーは、有効期限に「期限なし」か「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 のエラーの一覧は [エラー](/api-reference/errors) を見てください。
