認証

API キー（連携に推奨）

API キーは、アカウントのメンバーに紐付いた個人アクセストークンです。

作成は 設定 → プラグイン → RolChat API キー で行います。シークレットは一度だけ表示され、その後は最初の10文字だけが表示されます。RolChat は SHA-256 ハッシュのみを保存します。
形式: rcp_ に続いて、base64url でエンコードされた32バイトのランダム値。全体で約45文字です。このプレフィックスにより、ログ内でキーを見分けやすく、セッショントークンとも区別できます。
スコープ: キーの作成時に、固定された機能のカタログから選びます。キーは作成したメンバーの権限を超えることはできません。呼び出しのたびに、その機能がキーのスコープに含まれていること、かつメンバーが引き続きその機能を持っていることの両方が確認されます。メンバーの役割を狭めれば、キーも同様に狭まります。
有効期間: キーが自動で失効することはありません。キーの取り消しはプロフィールページ、または DELETE /api/v1/tokens/:id で行い、取り消しは即座に反映されます。その場でのローテーションはないため、取り消してから新しいキーを作成してください。
作成と取り消しは監査ログに記録されます。

ベアラートークンとして送信します。API キー専用のヘッダーはありません。

curl https://api.rolchat.com/api/v1/contacts?limit=20 \
  -H "Authorization: Bearer rcp_…" \
  -H "X-Account-Id: 7c1d2c6e-…"

プラグインの API キーによるリクエストは、1分あたり300回に制限されます。

JWT セッション

ウェブアプリとモバイルSDKは、メールアドレスとパスワード（または Google または Apple）でサインインし、トークンのペアを受け取ります。

トークン	有効期間	備考
アクセストークン	15分	RS256。`/.well-known/jwks.json` の JWKS で検証
リフレッシュトークン	30日	リフレッシュのたびにローテーションされます。ローテーション済みのトークンを再利用すると、チェーン全体が失効します

クレーム: sub（ユーザー）、acc（アカウント）、rl（役割）、サイト単位の役割の場合は sts（許可されたサイト）。

POST /auth/login、/auth/refresh、/auth/swap-company、/auth/logout は、次に説明する X-Account-Id ヘッダーを付けてはいけない、唯一の認証フローのエンドポイントです。

`X-Account-Id` ヘッダー

上記の4つを除くすべての認証済みリクエストには、操作対象のアカウントを含める必要があります。

X-Account-Id: <account uuid>

サーバーは、ヘッダーがトークンの acc クレーム（または API キーのアカウント）と一致することを確認します。ヘッダーがない場合は 400 missing_required_header、一致しない場合は 403 account_context_mismatch になります。このヘッダーは、クライアントのバグや再送されたトークンによって、別のテナントのデータが気付かれないまま読み取られることを防ぐためにあります。不一致はクエリが実行される前に拒否され、すべてのログ行はトークンをデコードしなくてもアカウントに紐付けられます。

複数の会社に所属するユーザー

1人が複数の会社に所属できます。会社ごとに独自のトークン（独自の acc クレーム）があります。切り替えるには次のようにします。

POST /api/v1/auth/swap-company
Authorization: Bearer <current access token>

{ "account_id": "<target uuid>" }

切り替え先は、呼び出し元の available_companies（ログイン時に返されます）のいずれかである必要があり、そうでない場合は 403 forbidden になります。レスポンスは、切り替え先に限定された新しいアクセストークンとリフレッシュトークンのペアです。古いリフレッシュトークンは失効し、auth.account.swapped 監査イベントが記録されます。

多要素認証

TOTP ベースの MFA はメンバーごとに登録でき、アカウントごとに必須にできます。有効な場合、POST /auth/login はチャレンジを返し、セッションは POST /auth/mfa/verify で完了します。バックアップコードは登録時に発行されます。

サインインの保護

サインインのルートは、IP ごとに1分あたり10回、メールアドレスごとに15分あたり5回に制限されます。
サインインに10回失敗すると、そのメールアドレスは30分間ロックされ、レスポンスには code: account_locked が含まれます。
reCAPTCHA はアクション（登録、サインイン、パスワードリセット）ごとに有効にでき、公開の初期設定は GET /api/v1/captcha から提供されます。

認証