トークンと認証

共有トークンと個人トークンの違い、要求の送り方、失敗したときの見方。

要求の送り方

API の要求には、Authorization ヘッダーでトークンを付けます。

export CR_TOKEN="発行された値をここへ設定"
curl https://comment-review.fsmarketing.workers.dev/api/reviews/review_example01 \
  -H "Authorization: Bearer $CR_TOKEN"

JSON の本文を送る操作では Content-Type: application/json を付けます。HTML を送る操作では、API リファレンスに記載されたマルチパートのフォームを使います。

Cookie のログインと Bearer トークンを同時に送った場合、API では Bearer トークンを使います。トークンをブラウザの画面用の要求へ付ける必要はありません。

トークンの種類

共有トークンは、既存のサービス連携で使うトークンです。個人トークンは、ログインと個人トークンで自分のアカウントから発行し、自分の名義で記録するトークンです。

種類	主な用途	認証方式の名前
エージェント用	文書を読み、AI レビューの run とコメントを操作する	`agentToken`
取り込み用	文書の一覧・取得、HTML の配信と版の更新を行う	`importToken`
管理用	題名・タグ・共有先を変え、文書を削除する	`manageToken`
個人トークン	本人として文書・共有・コメントの操作を行う	`personalToken`

API リファレンスの各操作では、security 欄に使える方式を示しています。方式が複数ある操作は、いずれか 1 つのトークンで呼べます。

個人トークンの範囲

個人トークンは発行時に範囲を選びます。省略したときは comments だけになります。

範囲	対象
`docs`	文書の作成・配信、版の追加、題名の変更、削除
`access`	共有状態、招待、招待の削除、役割の変更
`comments`	コメント、返信、解決、再オープン、AI レビューの操作
`org`	組織のメンバーと組織管理者の登録、変更、停止、削除。

文書の読み取り、本人情報、個人トークンの一覧・取り消しは、どの範囲でも使えます。選んだ範囲の外の書き込みは 403 と insufficient_scope になります。

個人トークンの扱い

個人トークンの値は発行時の応答で 1 回だけ返ります。API は後から値を再表示しないため、安全な保管場所へ保存してください。
トークンは発行から 90 日で期限切れになります。期限は GET /api/me、GET /api/me/tokens、または応答の x-cr-token-expires-at で確認できます。
個人トークンの識別子は監査と一覧に使う値で、トークンの値とは別です。識別子の例は pt_example01 です。
トークンの値をソースコード、ログ、チャット、URL に書かないでください。CLI を使う場合は CLI（cr）の保管規則に従ってください。

社外利用

社外・クライアントの利用には、組織管理者による台帳への登録と、案件の役割の付与が必要です。

失敗したとき

応答	見方
`401 authentication required`	トークンが無い、期限切れ、取り消し済み、または利用できるメンバーではありません。
`403 insufficient_scope`	個人トークンの範囲に操作が含まれていません。必要な範囲を選んで発行し直してください。
`403 forbidden`	範囲は足りていますが、文書の役割や操作の条件を満たしていません。
`404`	文書・コメント・識別子が存在しないか、利用者から見えません。

応答の JSON にある error を機械的な分岐に使い、本文の説明文は表示用に扱ってください。操作ごとの項目と応答は API リファレンスで確認できます。