Lesstep
GitLab.com・Self-Managed・アクセストークン・2026年10月24日に確認

GitLab の「insufficient_scope」「The request requires higher privileges than provided by the access token.」

「この呼び出しには、アクセストークンが持つより上の権限が要る」という意味です。トークンは有効ですが、この API の呼び出しに要る権限（スコープ）を付けずに作られています。GitLab は HTTP 403 で断り、受け付ける権限を答えの中に書いています。そのどれかを付けてトークンを作り直し、古いトークンを入れていた所を差し替えます。古いトークンのローテーション（Rotate）では直りません。新しいトークンも同じ権限のままだからです。

答えの全体

GitLab が組み立てる形です（lib/api/api_guard.rb）。api か read_api を持つトークンなら通る呼び出しの例：

HTTP 403
WWW-Authenticate: Bearer realm="Protected by OAuth 2.0", error="insufficient_scope",
  error_description="The request requires higher privileges than provided by the access token.", scope="api read_api"

{"error": "insufficient_scope",
 "error_description": "The request requires higher privileges than provided by the access token.",
 "scope": "api read_api"}

scope は、この呼び出しを通せる権限を空白で区切って並べたもので、どれか1つあれば足ります。GitLab の版によっては、何かを変える呼び出しでも read_api を並べます（2023年の報告では、MR の作成で {scope: api read_api}）。ただ read_api は読むだけなので、変えるときに足すのは api です。

道具によっては最初の1行や「403 Forbidden」しか出しません。答えの全体を見るには、失敗した住所を curl で呼びます。

curl -i --header "PRIVATE-TOKEN: your-token" "https://gitlab.com/api/v4/the/address/that/failed"

トークンにいま付いている権限は、GitLab の Personal access tokens の画面で、トークンごとに並んでいます。

答えが 401 の「invalid_token」なら、トークン自体の期限が切れたか、取り消されています。トークンに何が起きたかへ。

どの権限で何ができるか

GitLab のアクセストークンの権限の説明より：

なので、Git のためだけに作ったトークン（read_repository や write_repository）は API のほとんどの呼び出しで insufficient_scope になり、read_api のトークンは最初に何かを変えたときにこれになります。プロジェクトとグループのアクセストークンも権限は同じです（read_user だけは個人アクセストークン専用）。

JetBrains の IDE に入っている GitLab の機能については、JetBrains のヘルプが api と read_user の権限を付けたトークンを求めています（GitLab のアカウントの設定）。

権限を付けてトークンを作る

  1. GitLab の右上の自分のアイコン → Edit profile → 左の Access > Personal access tokens（2026年10月24日の GitLab の説明での名前。古い版では違います）。Generate token の一覧から Legacy token を選ぶ。
  2. 名前・期限・権限を入れる。権限は、今までのものに scope のどれか（変えるなら api）を足す。入力済みの画面を開くこともできます。例：https://gitlab.com/-/user_settings/personal_access_tokens?name=IDE&scopes=api（入力済みで開く方法。Self-Managed ならそのサーバーの住所で）。
  3. トークンをコピーする。GitLab が見せるのは、その画面を離れるか読み直すまでです。
  4. 古いトークンを入れていた所に新しいトークンを入れ、同じ画面で古い方を取り消す（Revoke）。ここで Rotate を押しても直りません。元と同じ権限のトークンができるだけです。

IntelliJ IDEA で GitLab の MR とパイプラインを見るなら

Lesstep は、JetBrains IDE（2024.1 以降）のプラグインを2つ作っています。Merge Request Inbox for GitLab と Pipeline Inbox for GitLab CI です。どちらも GitLab を read_api で読み、api で変えます。GitLab が insufficient_scope と答えたときは、トークンに要る権限（読むなら read_api か api、変えるなら api）を画面に出し、設定を開けるようにします。設定には、名前と権限を入力済みで GitLab の作成の画面を開くリンクがあります（GitLab 16.7 以降）。読むのは無料、承認・コメント・マージや、パイプラインの再実行・取り消し・実行は Pro（月 US$1.50・30日間の無料試用つき）です。画面は日本語です。

GITLAB は GitLab Inc. の商標、IntelliJ IDEA は JetBrains s.r.o. の商標です。このページは GitLab Inc.・JetBrains のいずれとも提携しておらず、承認も受けていません。

ほかに：GitLab のマージの断り（405・409・422） · GitLab の承認の断り（401・409） · GitLab のコメント・スレッドの断り（400・403） · GitLab のマージリクエストが作れない（409・422・400） · GitLab のリベースの断り・失敗（403・409） · GitLab の MR の一覧の断り（400・404） · GitLab の MR の変更が欠ける（「1000+」・too_large） · GitLab の 429「Retry later」（回数の上限） · GitLab の「compare_timeout」（差分の上限） · JetBrains の IDE で GitLab のマージリクエストを扱う · JetBrains の IDE で GitLab のパイプラインを扱う · English