あなたの管理下にある、範囲を限定したアクセス

接続はワークスペースのトークン

ワークスペースのオーナーと管理者は、開発者ページで接続を作ります。各接続は、一つのワークスペースと一つの用途に結び付いたBearerトークンです。restトークン（sw_rest_...）は/api/v1専用で、mcpトークン（sw_mcp_...）は/mcp専用です。

トークンはAuthorizationヘッダーで送ってください。URL、クエリ文字列、インポートファイル、ブラウザー用バンドルには決して入れないでください。

Authorization: Bearer sw_rest_...

スコープはロールで許される範囲を狭める

新しい接続は、読み取り専用の初期設定、workspaces:read、catalog:read、worlds:readで始まります。仕事に必要なものだけ追加してください。たとえば下書きの編集にはworlds:write、公開にはworlds:publishです。GET /meにはaccount:readが必要です。

スコープが、トークンを作った人のできること以上を許可することはありません。ロールは毎回のリクエストで読み直します。他のワークスペースのIDには404を返すため、トークンは見てはいけないものの存在を探れません。

機微なスコープは明示的に選ぶ

購読者のアドレス、訪問者のメッセージ、課金、削除、DNSへの書き込み、支出、チーム変更、Webhookにアクセスするスコープは、初めから選択されることはありません。追加する際は、先に再度サインインするよう求められます。対応するMCPツールは、トークンがそのスコープを持つまで非表示です。

トークンには一切利用できない操作もあります。承認の決定、casaやアカウントの削除と復元（サービス本体での再度のサインインが必要で、403 reauthentication_requiredを返します）、データのエクスポートです。

有効期限、ローテーション、失効

• トークンの有効期間は標準で30日、最長で90日です。
• ハッシュだけを保存するため、紛失したトークンは再表示できません。代わりに新しい接続を作ってください。
• ローテーションするには、新しい接続を作り、クライアントを切り替え、それから古い接続を失効させます。失効は、エージェントが待ち行列に入れた仕事も含め、次のリクエストから有効になります。

想定されるエラー

• 401：トークンが未指定、不明、期限切れ、失効済み、または別の用途向けです。
• 403 insufficient_scope：トークンに権限がありません。context.required_scopeに必要な権限名があり、レスポンスにはWWW-Authenticateヘッダーが付きます。
• 404：このトークンのワークスペースに、そのリソースは存在しません。

OAuthはまだ利用できない

OAuthサインインだけに対応するエージェントクライアントは、まだ接続できません。そのため、/.well-known/oauth-protected-resource/mcpには認可サーバーが掲載されていません。代わりに、クライアントのヘッダー設定で接続トークンを使ってください。