（おまけ）GWS（Google Workspace CLI）で躓く「スコープ」とは？権限不足エラー（403）の原因と対処法

2026.03.08 | 2 min read

📝 おまけ記事：
brief043・brief044・brief045 の GWS（Google Workspace CLI）連載の補足です。gws を使っていくと「権限がなくて使えない」と出て躓きやすいスコープについて、原因と対処をまとめました。内容は Google OAuth 2.0 スコープおよび gws 利用時のメモに基づきます。

GWS（Google Workspace CLI）（gws）でコマンドを実行したときに「403 Request had insufficient authentication scopes」など権限エラーになる原因は、ログイン時に付与したスコープ（権限の範囲）が足りていないためです。スコープとは何か・どう確認・追加するかを解説します。

スコープとは

スコープは、gws auth login 時に「どの Google サービスに、どの程度の権限（閲覧だけか・編集も含むか）を許可するか」を指定するものです。OAuth 2.0 の仕組みで、ログイン時に選んだスコープだけがトークンに紐づき、その範囲でしか API を呼べません。足りない操作をしようとすると 403 Request had insufficient authentication scopes が返ります。

現在のスコープを確認する

今のトークンに何が付いているかは次のコマンドで確認できます。

gws auth status

出力の scopes 配列が付与済みスコープです。操作別の「必要スコープ」と照らし合わせると、何が足りないか分かります。kasutera-gws-cli 等のリポジトリに同梱している scope_check.ps1 を使うと、現在のスコープを一覧表示したり、操作（filters / drive / calendar / vacation）ごとに不足スコープと推奨ログインコマンドを表示できます。

.\scope_check.ps1
.\scope_check.ps1 -For filters
.\scope_check.ps1 -ShowLogin full

403 が出たときの対処（再ログインでスコープを足す）

対処は必要なスコープを付けて再ログインすることです。gws auth login を再度実行し、ブラウザの同意画面で追加の権限を許可します。注意点：--scopes で指定したスコープのみが付与され、既存のスコープは上書きされます。複数サービスを使う場合は、必要なものをカンマ区切りでまとめて指定してください。

標準（多くの操作に対応）: gws auth login のみ。
サービスを絞る（@gmail.com でテストモード制限に引っかかる場合）: gws auth login --scopes drive,gmail,sheets,calendar
閲覧のみ: gws auth login --scopes readonly

操作・用途別の必要スコープ（要点）

代表例です。詳細は Google 公式の OAuth 2.0 スコープ一覧や各 API の認証ドキュメントを参照してください。

Gmail 送受信・ラベル・メッセージ読取: gmail.modify
Gmail フィルタ作成・不在時オート返信: gmail.modify と gmail.settings.basic の両方が必要。標準の gws auth login だけではフィルタ系は不足することがある。
Drive ファイル一覧・作成・削除: drive（閲覧のみなら drive.readonly）
Calendar 予定の表示・作成・編集: calendar（閲覧のみなら calendar.readonly）
Tasks: tasks / tasks.readonly
Sheets / Docs / Slides: spreadsheets, documents, presentations など

Gmail フィルタで 403 が出た場合の再ログイン例（他サービスは付かなくなるので、Drive 等も使うなら gws auth login でまとめて取り直すのが無難です）:

gws auth login --scopes https://www.googleapis.com/auth/gmail.modify,https://www.googleapis.com/auth/gmail.settings.basic

GWS（Google Workspace CLI）で使う全スコープ一覧（公式ベース）

以下は Google OAuth 2.0 Scopes および各 API 認証ドキュメントに基づく一覧です。gws が利用する Workspace 系 API のスコープを表形式でまとめています。

API	スコープ（略称）	説明
Gmail	`mail.google.com`	メールの読み・作成・送信・恒久削除（最大権限）
	`gmail.modify`	読み・作成・送信（恒久削除除く）※常用
	`gmail.readonly`	メール・設定の閲覧
	`gmail.send`	送信のみ
	`gmail.compose`	下書きの管理・送信
	`gmail.insert`	メールの追加
	`gmail.labels`	ラベルの表示・編集
	`gmail.metadata`	メタデータ（ラベル・ヘッダー）のみ、本文なし
	`gmail.settings.basic`	設定・フィルタの表示・編集・作成※フィルタに必須
	`gmail.settings.sharing`	転送等の機密設定（主にドメイン委任）
	`gmail.addons.current.*`	アドオン用（compose / message.action / message.metadata / message.readonly）
	※ フルURLは `https://www.googleapis.com/auth/` ＋上記（mail.google.com はそのまま）

API	スコープ（略称）	説明
Drive	`drive`	全ファイルの表示・編集・作成・削除
	`drive.readonly`	全ファイルの表示・ダウンロード
	`drive.file`	アプリで開いた/共有されたファイルのみ（非感度推奨）
	`drive.metadata.readonly`	メタデータのみ表示
	`drive.metadata`	メタデータの表示・管理
	`drive.appdata`	アプリの設定データのみ
	`drive.apps.readonly`	Drive アプリ一覧の表示
	`drive.activity` / `.readonly`	ファイルのアクティビティ記録
	`drive.scripts`	Apps Script の挙動変更

API	スコープ（略称）	説明
Calendar	`calendar`	カレンダーの表示・編集・共有・恒久削除
	`calendar.readonly`	カレンダーの表示・ダウンロード
	`calendar.events`	全カレンダーのイベント表示・編集
	`calendar.events.readonly`	イベントの表示のみ
	`calendar.freebusy`	空き情報の表示
	`calendar.settings.readonly`	Calendar 設定の表示
	`calendar.calendarlist` / `.readonly`	購読カレンダー一覧の表示・追加・削除
	`calendar.calendars` / `.readonly`	カレンダー本体のプロパティ・作成
	`calendar.acls` / `.readonly`	共有設定の表示・変更

API	スコープ（略称）	説明
Sheets	`spreadsheets`	スプレッドシートの表示・編集・作成・削除
	`spreadsheets.readonly`	スプレッドシートの表示
Docs	`documents`	ドキュメントの表示・編集・作成・削除
	`documents.readonly`	ドキュメントの表示
Slides	`presentations`	プレゼンの表示・編集・作成・削除
	`presentations.readonly`	プレゼンの表示
Tasks	`tasks`	タスクの作成・編集・整理・削除
	`tasks.readonly`	タスクの表示
People	`contacts`	連絡先の表示・編集・ダウンロード・恒久削除
	`contacts.readonly`	連絡先の表示・ダウンロード
Forms	`forms.body`	フォームの表示・編集・作成・削除
	`forms.body.readonly`	フォームの表示
	`forms.responses.readonly`	回答の表示
Keep	`keep`	Keep データの表示・編集・作成・恒久削除
	`keep.readonly`	Keep データの表示
Chat	`chat.messages`	メッセージの閲覧・送信・更新・削除・リアクション
	`chat.messages.readonly`	メッセージの閲覧
	`chat.messages.create`	メッセージの送信
	`chat.spaces` / `.readonly` / `.create`	スペース・会話の作成・メタデータ
	`chat.memberships` / `.readonly`	メンバーシップの表示・追加・削除

※ Docs/Sheets/Slides はファイル操作に drive または drive.file が必要な場合あり。出典: OAuth 2.0 Scopes for Google APIs, Gmail, Drive, Calendar 各公式ドキュメント。

参照ドキュメント（本記事の元ネタ）

本記事の内容は、kasutera-gws-cli プロジェクト内の以下のリソースにまとめています。gws を利用する環境に同梱したり、ローカルで参照してください。

GWS_AUTH_SCOPES_GUIDE.md — スコープの意味・プリセット（readonly / サービス名指定）・403 対処・Gmail フィルタ用スコープ・ブラウザ必須の説明。
GWS_SCOPE_REFERENCE.md — 操作・用途別の必要スコープ一覧、API 別の公式スコープ、略称⇔フル URL、現在のスコープ確認・付与のコマンド例。
scope_check.ps1 — 現在のスコープ表示、-ShowLogin full|gmail-filters|readonly で推奨ログインコマンド表示、-For filters|drive|calendar|vacation で操作別の不足チェックと再ログイン案内。

これらはすべて kasutera-gws-cli プロジェクト（ZIP）に同梱しています。スコープ確認や 403 対処を手元でやりたい場合は、下記からダウンロードして解凍し、.agent/skills/kasutera_master/resources/ および scripts/scope_check.ps1 を参照してください。

📦 kasutera-gws-cli.zip のダウンロード

kasutera-gws-cli は、本記事で紹介しているスコープ解説（GWS_AUTH_SCOPES_GUIDE.md・GWS_SCOPE_REFERENCE.md）と scope_check.ps1 に加え、Antigravity で gws を LLM から使うためのスキル一式をまとめた ZIP です。カステラスキルには、各操作で事前に必要になるスコープをスキル内（resources の GWS_SCOPE_REFERENCE.md・GWS_AUTH_SCOPES_GUIDE.md、scripts の scope_check.ps1 など）にまとめてあります。

スコープ関連 — 事前に必要になるスコープをスキルとして整理。GWS_AUTH_SCOPES_GUIDE.md、GWS_SCOPE_REFERENCE.md、scope_check.ps1（現在のスコープ表示・操作別不足チェック・推奨ログインコマンド表示）
Antigravity 用スキル — プロジェクトルートで開き、会話で「カステラ」と送ると環境チェック・公式 gws スキル同期・認証案内が動く
インストール障害対策 — GWS_CLI_INSTALL_ERROR_GUIDE.md（Windows で gws が動かない場合の対処）、check_env.ps1 など

※ OAuth 用の client_secret_xxx.json は ZIP に含まれません。利用時は Google Cloud コンソールで OAuth 2.0 クライアント ID の JSON を取得し、gws auth setup / gws auth login で認証してください。

📦 kasutera-gws-cli.zip をダウンロード（Antigravity 用 GWSCLI スキル＋スコープ解説一式）

以上、gws 利用で躓きやすいスコープと権限エラーの原因・対処の要点でした。入門・Antigravity 連携・業務での実例とあわせて参照してください。