# 認証

> 各Kanorio APIが受け付ける認証情報、権限の計算方法、およびトークンを安全にローテーション・無効化する方法について説明します。

> Markdown version of https://kanorio.com/ja/developers/authentication. Append `.md` to any developer docs URL for this format. Index: https://kanorio.com/llms.txt · MCP: https://app.kanorio.com/api/mcp
>
> Translated from the English original: https://kanorio.com/en/developers/authentication.md

各Kanorio APIはそれぞれ異なる呼び出し元を想定して構築されており、個別の認証情報を受け付けます。呼び出し元が誰のために動作しているかを確認し、適切な認証情報を選択してください。

| 認証情報 | プレフィックス | 権限の対象 | 対応API | 用途 |
|---|---|---|---|---|
| パーソナルアクセストークン | `knr_pat_` | ユーザー本人（選択したサイトと権限に限定） | Management API、MCP | スクリプト、CLI、キーを使用するコーディングアシスタント |
| サービスアカウントトークン | `knr_sa_` | サイト自体（個人ではない） | Management API、MCP | CI、スケジューラー、ユーザーの離脱後も稼働し続けるパートナーのバックエンド |
| OAuthアクセストークン | `knr_at_` | ユーザー本人（承認したアプリ経由） | MCPのみ | ClaudeやChatGPTなど、コネクタが組み込まれたアシスタント |
| プレビュー用トークン | `knr_pv_` | 特定のサイトのドラフトへの読み取り専用アクセス | Content Delivery API | フロントエンドでのドラフトモード |
| カスタマートークン | `knr_cat_` | 特定のサイトにログインした顧客1名 | Customer API、制限付きContent Delivery APIの読み取り | フロントエンドでのログイン、購入済みコンテンツ、注文 |

Content Delivery APIでは、公開されているコンテンツに対して認証情報は不要です。

## Management API

`https://app.kanorio.com/api/v1`へのすべてのリクエストにおいて、トークンをBearer認証情報として送信してください。

```bash
curl https://app.kanorio.com/api/v1/sites \
  -H "Authorization: Bearer knr_pat_..."
```

### パーソナルアクセストークン

[アカウント設定 › APIアクセス](https://app.kanorio.com/account/api-access)から作成します。作成時には以下を選択します。

- **サイト:** 特定のサイト、または今後作成するサイトを含むすべてのサイト。新しいサイトを作成するには、すべてのサイトへのアクセス権が必要です。
- **権限:** プリセット（読み取り専用、コンテンツ編集、フルアクセス）または個別の権限。
- **有効期限:** トークンには必ず有効期限があります。期限が切れる前に、メールと受信トレイに通知が届きます。

サイト上でのトークンの有効な権限は、トークンが許可する範囲と、そのサイトにおけるあなたのロールが許可する範囲の共通部分となります。フルアクセストークンであっても、あなたが閲覧者として設定されているサイトを編集することはできず、サイトの公開停止はサイト所有者のみが実行可能です。

選択したプリセットに関わらず、トークンには決して付与されない権限があります。これには、ニュースレターの送信やスケジュール設定、データのエクスポート、返金処理、連絡先の削除、メンバーや請求の管理が含まれます。エージェントはニュースレターのドラフトを作成できますが、送信は管理画面から人が行う必要があります。

### サービスアカウント

サービスアカウントは個人ではなくサイトに属します。作成者がチームを離れても動作し続け、サービスアカウントを無効化すると、そのアカウントが発行したすべてのトークンが即座に無効になります。

1. [サイト設定 › 開発者](https://app.kanorio.com/settings/developer)を開き、サービスアカウントを追加します。自分自身が持つ権限のみを付与できます。
2. サービスアカウントを開き、トークンを発行します。"GitHub Actions"のように、使用する場所に合わせた名前を付けてください。`knr_sa_`で始まる値は一度のみ表示されます。

サービスアカウントは、そのサイト内でのみ機能します。サイトの作成や全サイトの一覧取得といったアカウントレベルの操作を行うと、`403 FORBIDDEN`が返されます。[OpenAPIドキュメント](https://app.kanorio.com/api/v1/openapi.json)の各操作には、受け付け可能な呼び出し元が`x-kanorio-principals`に記載されています。`SERVICE_ACCOUNT`が含まれる操作は、サービスアカウントトークンを受け付けます。

サービスアカウントの権限を制限すると、既存のトークンにも即座に反映されます。権限を拡大した場合は、その後に発行されたトークンのみに適用されます。

### スコープ

[Management APIリファレンス](https://kanorio.com/en/developers/management-api)の各操作には、必要な権限が示されています。OpenAPIドキュメントには同じ値が`x-kanorio-required-scope`として記載されています。必要な権限がないトークンを使用すると`403 FORBIDDEN`が返されます。現在のトークンで何ができるかを確認するには、`GET /whoami`を呼び出してください。

## MCP

`https://app.kanorio.com/api/mcp`のMCPサーバーは、パーソナルアクセストークンおよびサービスアカウントトークンに加え、OAuth 2.1アクセストークンを受け付けます。組み込みコネクタを持つアシスタントは、認証サーバーを自動的に検出し、ブラウザ上でアクセス承認を求めます。OAuthアクセストークンはMCPサーバーに紐付いており、RESTエンドポイントでは拒否されます。[MCP](https://kanorio.com/ja/developers/mcp)を参照してください。

## Content Delivery API

公開されたコンテンツはパブリックであり、エッジキャッシュされるため、ブラウザから直接呼び出すことができます。

- **異なるオリジンからのブラウザ呼び出し**には、[サイト設定 › 開発者](https://app.kanorio.com/settings/developer)の**許可されたオリジン**にそのオリジンを追加する必要があります。`localhost`および任意のポートの`127.0.0.1`は常に許可されます。CORSはブラウザが読み取り可能な内容を制御します。これは認証の境界ではなく、プレビュー用トークンなしでドラフトが提供されることはありません。
- **ドラフトのプレビュー:** 同じ設定ページ、または`POST /sites/{id}/preview-tokens`を使用して`knr_pv_`プレビュー用トークンを作成します。サーバーから`X-Kanorio-Preview: knr_pv_...`として送信してください。プレビューのレスポンスはキャッシュをバイパスし、保存されることはありません。

## Customer API

顧客はパスワードなしでサインインします。サイト所有者は**サイト設定 › 顧客アカウント**で有効にする方法を選択します。サイトドキュメントの`customerAccess.methods`には、有効な方法が表示順にリストされています。すべての方法は最終的に同じ`knr_cat_`セッショントークンとなります。

- **メールコード**（`email_code`、常に有効）および**マジックリンク**（`email_link`）: メールアドレスを指定して`POST /api/v1/customer/auth/challenge`を呼び出すとコードが送信されます。まず`GET /api/v1/customer/auth/protection`からボットチェックを取得します。組み込みチェック（`provider: "kanorio"`）の場合は`@kanorio/sdk`の`solveProtectionChallenge`で解決し、フィールドをリクエストに含めます。所有者のTurnstile、reCAPTCHA、またはhCaptchaキーを使用する場合は、`siteKey`と`action`でウィジェットをレンダリングし、そのトークンを`captchaToken`として送信します。その後、`{ "method": "code", "email", "code" }`または`{ "method": "link", "token" }`を指定して`POST /api/v1/customer/auth/verify`を呼び出します。
- **Google**（`google`）: `{ "method": "google", "baseUrl": <ページのオリジン> }`を指定して`POST /api/v1/customer/auth/oauth/start`を呼び出すとプロバイダーURLが返されるので、ブラウザをそこにリダイレクトします。Kanorioが同意画面をホストし、`?handoff=`を付与してブラウザを`baseUrl`に戻します。60秒以内に`{ "method": "handoff", "token" }`を指定して`POST /api/v1/customer/auth/verify`で交換してください。Googleアカウントのメールが未確認の場合、顧客には代わりにメールコードが送信され、`?email=&verify=1`が付与された状態でページに戻ります。
- **パスキー**（`passkey`）: `POST /api/v1/customer/auth/passkey/options`を呼び出し、オプションを使用して`navigator.credentials.get()`を実行した後、アサーションと`challengeId`を指定して`POST /api/v1/customer/auth/passkey/verify`を呼び出します。サインイン済みの顧客は`/api/v1/customer/passkeys`でパスキーを管理できます。パスキーはサイトのプライマリドメインに紐付いているため、認証プロセスはそのオリジンで実行する必要があります。

サインインUIで`POST /api/v1/customer/auth/challenge`からのレスポンスを処理します。

| コード | 対処方法 |
|---|---|
| `429 RATE_LIMITED` | `retryAfter`秒待機してから、再度試行するよう顧客に促してください |
| `403 BOT_PROTECTION_FAILED` | 新しいチャレンジを取得（またはウィジェットをリセット）して再送信してください |
| `503 SERVICE_UNAVAILABLE` | ログイン機能が一時的に利用できません。再試行を促してください |
| `503 SHARED_SENDER_PAUSED` | 現在このサイトではメールログインが一時停止されています。パスキーやGoogleログインを提案するか、後で試すよう顧客に伝えてください |

`200`が返されても、メールが送信されたかどうかは明かされません。Kanorioはサイトのサインイン数に応じてボットチェックを調整します。`/auth/protection`からのチャレンジは、表示可能なウィジェット（`visible: true`）やより困難な組み込みパズルを要求する場合があるため、非表示フローを前提とせず、常に取得したチャレンジに基づいてレンダリングしてください。

Customer APIの呼び出しおよび制限付きのContent Delivery APIの読み取りには、トークンを`Authorization: Bearer knr_cat_...`として送信してください。

顧客トークンは、そのサイトにおけるその顧客のみを表します。他の誰かのデータを読み取ったり、Management APIを呼び出したりすることはできません。[`<kanorio-login>`](https://kanorio.com/ja/developers/elements)要素を使用すると、このフローが自動的に実行されます。

## トークンのローテーションと無効化

- **ローテーション:** パーソナルアクセストークンのメニューからローテーションを行います。Kanorioは同じ設定で新しいトークンを発行し、古いトークンは選択した猶予期間（なし、1時間、1日）まで有効に保たれます。漏洩が疑われる場合は「なし」を選択してください。
- **無効化:** トークンを無効化すると即座に使用停止となります。そのトークンを使用した次のリクエストには`401 UNAUTHORIZED`が返されます。すでに完了した操作がロールバックされることはありません。
- トークンを使用して実行されたアクティビティは、サイトのアクティビティログに、そのトークンの所有者またはサービスアカウントの名前で記録されます。

## トークンの安全な管理

- トークンは環境変数またはサーバー上のシークレットマネージャーに保存してください。`NEXT_PUBLIC_`を接頭辞に付けたり、モバイルアプリに含めたりしないでください。
- トークンをAIチャットに貼り付けないでください。実際のツールは設定ファイルから読み取ります。
- ツールごとに1つのトークン、統合ごとに1つのサービスアカウントを使用し、個別に無効化できるようにしてください。
- 各トークンには、動作に必要な最小限のサイトと権限のみを付与してください。