はじめに

認証

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

各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認証情報として送信してください。

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

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

アカウント設定 › APIアクセスから作成します。作成時には以下を選択します。

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

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

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

サービスアカウント

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

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

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

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

スコープ

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を参照してください。

Content Delivery API

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

異なるオリジンからのブラウザ呼び出しには、サイト設定 › 開発者の許可されたオリジンにそのオリジンを追加する必要があります。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>要素を使用すると、このフローが自動的に実行されます。

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

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

トークンの安全な管理

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