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

## 要求の送り方

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

```bash
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 トークンを使います。トークンをブラウザの画面用の要求へ付ける必要はありません。

## トークンの種類

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

| 種類 | 主な用途 | 認証方式の名前 |
|---|---|---|
| エージェント用 | 文書を読み、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）](/cr) の保管規則に従ってください。

## 社外利用

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

## 失敗したとき

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

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