Authentication — API key と OAuth、 actor、 scope

/v1/... は 2 系統の認証を受け付ける。 JWT (内部 frontend 用) は受け付けない。

方式	ヘッダー	actor	用途
API key	`Authorization: Bearer tcha_live_…` または `X-Api-Key: …`	`app`	server-to-server / CI / 社内ツール
OAuth 2.1 token	`Authorization: Bearer tcha_at_…`	`user` / `agent` (token に依存)	ユーザー代行 / agent (LLM) 代行

actor モデル

すべての /v1/... リクエストは以下の actor を 1 つ持つ:

actor	意味
`user`	OAuth トークンを持つ人間ユーザーの代行操作
`app`	組織またはユーザーに install された外部アプリ (server-to-server)
`agent`	LLM / MCP / OpenClaw など agent runtime (人間が責任を持つ delegate)

agent は人間の assignee と混ぜず、「人間が責任を持ち、 agent が補助する」モデル (Linear と同様)。操作の audit log にも actor=agent が記録される。

API key

形式

tcha_live_<32 bytes base64url>
tcha_test_<32 bytes base64url>

prefix で本番 / 検証用を分離
256bit ランダム、 SHA-256 hash のみ DB 保存 (平文は never)
比較は constant-time

発行と revoke

UI: /settings/developer

発行直後の token は その時のレスポンスでしか取得できない
一覧表示には prefix + 末尾 4 文字 だけが出る
revoke 後の token は即座に 401

Scope

API key は発行時に scope を選ぶ。詳細は下の「Scope 一覧」を参照。

OAuth 2.1

外部 SaaS / Zapier / MCP / OpenClaw connector UI / ユーザー代行に使う。

Authorization Code + PKCE 必須
refresh token は rotation + reuse detection
consent screen に scope 表示
token audience は https://api.tas-cha.com/v1 または https://api.tas-cha.com/mcp のいずれかに pin
access token は tcha_at_ prefix

OAuth app の発行は 管理者による登録のみ。セルフ登録 UI は提供していない。

Scope 一覧

resource:action の最小単位。 1 token = 1 scope セット。

Scope	意味
`me:read`	`/v1/me` 自分のプロフィール読み出し
`organizations:read`	所属組織一覧
`rooms:read`	Room 一覧 / メンバー読み出し
`rooms:write`	Room 設定変更 (※ Write API)
`messages:read`	メッセージ読み出し
`messages:write`	メッセージ送信 (※ Write API)
`tasks:read`	タスク一覧 / 詳細
`tasks:write`	タスク作成 / 更新 (※ Write API)
`records:read`	議事録読み出し
`records:write`	議事録作成 / 更新 (※ Write API)
`files:read`	ファイルメタ / DL
`files:write`	ファイル UL
`webhooks:read`	Webhook 一覧
`webhooks:write`	Webhook 作成 / 更新
`events:read`	イベントログ
`mcp:tools`	Remote MCP の tool 呼び出し
`agent:invoke`	Connector で agent 実行

Scope 評価の不変則

scope だけで許可しない。以下の AND 条件 で評価される:

authentication OK
  AND token に必要 scope が含まれる
  AND actor (user/app/agent) と subject の billing entity が一致する
  AND ドメイン側 RBAC (Room membership / Organization membership / Room type)
  AND short-window rate limit OK
  AND 月次 API units 残量 OK
  AND idempotency key OK (write only)

DM ルーム (roomType=1) は Public API では常に拒否される (BOLA 対策で room_not_found で返す)。

actor + 既存権限の関係

actor	検証順序
`user`	OAuth token → 代行対象 user の RBAC (frontend ログイン user 相当)
`app`	API key → install された organization / user 範囲のリソースのみ
`agent`	OAuth (PKCE) → delegate 元 user の権限を超えない、 audit log に明示記録

組織に install された API key は その組織が見える範囲だけ を扱える。別組織や個人領域へのアクセスは 404 で塞ぐ。

Audit log

すべての /v1/... リクエストは監査ログに記録される:

requestId, surface, method, routePattern, statusCode
auth method (api_key / oauth_bearer)
actor, scopes, organizationId / userId
API key id / external token id
API units cost

紛失 / 漏洩時の被害範囲特定のため、監査ログは 7 年保持。

OAuth 2.1 フロー

Endpoint	役割
`GET /.well-known/oauth-authorization-server`	AS metadata (RFC 8414)。 MCP クライアントの discovery
`GET /oauth/authorize`	認可リクエスト検証 → 同意画面 (`/oauth/consent`) へ 302
`POST /oauth/token`	code 交換 / refresh rotation (urlencoded)
`POST /oauth/revoke`	token 失効 (RFC 7009)。 refresh の失効は grant 全体に及ぶ

規約:

PKCE (S256) 必須 (public / confidential とも)。 plain は拒否
redirect_uri は 登録値と完全一致 のみ。検証前 redirect はしない
confidential client は token endpoint で client_secret 必須
access token: tcha_at_ / 1 時間。 refresh token: tcha_rt_ / 30 日 (family 起点)
refresh は rotation + reuse detection: 使用済み refresh の再提示で family 全 token を失効
resource パラメータは token の audience に固定され、 MCP (https://api.tas-cha.com/mcp) では一致しない token を 403 にする
アプリ登録は 管理者による手動登録。セルフサービス登録は提供していない

actor モデル​

API key​

形式​

発行と revoke​

Scope​

OAuth 2.1​

Scope 一覧​

Scope 評価の不変則​

actor + 既存権限の関係​

Audit log​

OAuth 2.1 フロー​