AIものさし

Slack APIのmissing_scopeをbot token・user token・インストール状態から切り分ける

Slack APIの missing_scope は、呼び出したAPI methodが必要とするOAuth scopeを、リクエストのtokenが持っていないときに返るエラーです。

AIものさし編集部

目次

まず結論：scopeを足す前に、method・token・install先を照合する

Slack APIの missing_scope は、呼び出したAPI methodが必要とするOAuth scopeを、リクエストのtokenが持っていないときに返るエラーです。scope名を設定画面へ追加しただけでは直らないことがあります。scopeを追加したアプリが対象workspaceへ再インストールされておらず、古いtokenを使い続けている、bot tokenとuser tokenを取り違えている、違うworkspaceのtokenを呼び出しに使っている、といった原因があるためです。

最初にAPI responseの error、needed、providedを安全に確認し、呼び出したmethodの公式ページに記載された必要scope、実際のtoken種別、対象workspaceのinstall状態、実行中のtokenの出所を別々に調べます。access tokenそのものをログ、Issue、画面共有へ出さないでください。

ここで大切なのは、scopeを闇雲に追加することではありません。必要最小限の権限を選び、そのscopeを使うtokenを、正しいアプリとworkspaceで取得し直すことです。実際のApp設定、API request、Workspaceは与えられていないので、この記事は切り分けの手順を示し、個別のmissing_scope原因を断定しません。

responseから必要scopeと提供scopeを読む

Slack Web APIのエラーresponseに missing_scope がある場合、neededはmethodが必要とするscope、providedはその呼び出しで認識されたscopeの一覧を示す例があります。methodによってresponse形式や、scope以外の制約は異なります。responseを確認するときは、HTTP statusとJSONの ok、error、needed、providedを見ます。token値、Authorization header、Cookieは保存しないでください。

たとえば必要scopeに chat:write、提供scopeにそれがなければ、まず当該methodがbot tokenを受け付けるのか、user tokenが必要なのかを公式methodページで確かめます。scope名が違うと即断せず、旧scope、resource-based scope、tokenタイプの互換性も確認します。必要scopeがresponseに出ないAPIでは、該当methodの公式ドキュメントを根拠にします。

token値を画面に貼らず、実行環境内で以下の対応表を作ります。

表は横にスクロールできます

項目確認すること残す記録
API method実際のmethod名・呼び出し先method名
Errorerrorと必要scope情報error名とscope名のみ
Token typebot / user / app-levelなど種別のみ
Workspacetokenが認可されたteam安全に扱えるworkspace識別子
Apprequestで使うアプリApp IDなど
Installscope追加後に再認可済みかYes / No / Unknown

この表にtokenの中身や秘密値を転記してはいけません。

bot tokenとuser tokenは代替できるとは限らない

Slackのbot tokenはアプリのbotとして動作し、user tokenは認可したユーザーの代理として動作します。methodが必要とするscopeだけでなく、どちらのtoken種別が対応しているかも確認してください。bot tokenへuser scopeを追加すれば同じ操作ができる、またはuser tokenならbot scopeを使える、と一律に考えることはできません。

Slackのtoken type公式説明によると、bot tokenはアプリに紐づく一方、user tokenは認可ユーザーに紐づき、tokenごとに利用できるscopeと役割が異なります。Workflow tokenなど一部の種類には制約があり、通常のbot tokenと同じ機能を持つとは限りません。API methodページの「Accepted scopes」や対応token typeを確認します。

たとえばチャンネルへ投稿するmethodを呼ぶ場合も、アプリとして投稿するのか、ユーザーの権限で代理投稿するのかで必要な認可の設計が変わります。実行主体を要件から決め、botかuserかを選び、その種別に対応するscopeだけを要求します。単にエラーを消すためにuser scopeへ切り替えると、ユーザー本人の権限で動く設計へ変わるため、影響を理解せず変更してはいけません。

scopeを追加しても既存tokenが自動更新されるとは限らない

SlackアプリのscopeはOAuth認可で要求され、ユーザーまたはworkspaceが許可した内容がtokenへ結びつきます。App Manifestやアプリ設定でscopeを変更しても、すでに発行されたtokenのscopeが自動的に増えるとは限りません。Slackの公式配布・ライフサイクル資料は、新しい権限が既存installに必要となる変更について、該当workspaceで再インストールが必要と説明しています。

復旧時は次の順で確認します。

  1. App設定で追加したscopeが正しいtoken typeの欄にあるか。

  2. 対象workspaceがそのアプリをinstallしているか。

  3. scope追加後にそのworkspaceで再認可が完了したか。

  4. アプリが新しいOAuth結果を安全に保存したか。

  5. API呼び出しが古いtoken、別環境のtoken、別workspaceのtokenを参照していないか。

再インストールはアプリの設定や利用者に影響する操作です。ユーザーに許可されたscope、管理者承認が必要なworkspace、インストール方式を確認して行ってください。必要なscopeを追加した後、再認可やtoken交換を行わず、環境変数だけを変更して済ませようとしないでください。

scopeを増やす前にmethod要件を確定する

scopeはmethodや操作に応じて異なります。あるmethodのエラーで必要だったscopeを、別のmethodにもそのまま適用しないでください。Slack API methodの公式ページで次を確認します。

  • 必須scopeと任意scope

  • 対応するtoken type

  • bot/userのいずれが操作主体になるか

  • 対象リソースへのアクセス条件

  • workspaceや管理者による追加制約

  • classic/legacy scopeと現在のgranular scopeの差

error responseに needed と providedがあれば、公式method要件との照合に使えます。ただしscopeが一致しても、チャンネル参加、リソース共有、管理者ポリシー、対象ID誤りなど他の権限・リソース条件が原因の可能性があります。method名だけで必要scopeが確定しない場合は、APIの正式なreferenceを開き、アプリに付与済みの権限を必要以上に広げないようにします。

手順：古いtokenや別workspaceの取り違えを防ぐ

次の手順は、APIを呼ぶ開発者が自分のapp設定へアクセスできることを前提にしています。

  1. 失敗したrequestを特定する。 API method、実行環境、時刻、workspaceを記録し、本文やAuthorization headerからtoken値を除外します。

  2. responseを読む。 JSONのerrorと、利用できる場合はneeded/providedを記録します。tokenはredactします。

  3. methodの公式要件を開く。 必須scopeと受け付けるtoken種別を確認し、response情報と比較します。

  4. token typeを確認する。 App設定、OAuth応答のmetadata、secret manager上の変数名などから、bot/user等の種類を値を出さず確認します。

  5. workspaceとappを照合する。 tokenを発行したApp ID、workspaceと、requestが対象にするapp/workspaceが一致しているか確認します。

  6. scopeの追加先を確認する。 bot token用scopeかuser token用scopeか、methodが受け付ける種類に合うか確認します。

  7. 再インストール要件を確認する。 scope追加で既存tokenへの再認可が必要なら、workspaceの管理者・配布方式に沿って行います。

  8. 新しい認可結果を保存する。 アプリが正しいtokenを安全なsecret storeへ保存し、旧tokenを参照する環境がないか調べます。

  9. 最小範囲で再試験する。 対象workspace、対象method、非本番または安全なテスト対象で実行し、errorと必要なscope名だけ記録します。

  10. 不要な権限を棚卸しする。 動作確認後も、要求scopeをReader Jobに必要な範囲へ保ちます。

チームのApp設定を変更したり、workspaceへ再インストールする権限がなければ、自分で権限を増やそうとせず管理者へ依頼します。user tokenへ切り替えた場合、操作の主体・監査・利用者権限に関わるので設計担当者の確認も必要です。

原因別の切り分け表

表は横にスクロールできます

観測主な候補次の確認
neededにscopeがありprovidedにないscope未認可method要件とtoken type
App設定にはscopeがあるがprovidedにないscope追加後に再認可していないworkspace install状態、token発行時点
providedに想定scopeがない古いtokenや別tokenを参照secret storeのkey mapping、環境
scopeはあるがmethodが失敗するtoken type、リソース権限、ID誤りmethod受け入れ条件、resource access
botでは失敗しuserでは成功操作主体の権限差user tokenの使用が要件に合うか
一つのworkspaceだけ失敗installや管理者ポリシーの差workspace別installと承認
scope追加後も結果が同じ古い認可結果や別環境OAuth flow、保存先、実行環境

この表は候補の整理です。特定の結果だけで原因を断定せず、method要件・token種別・workspace・使われているtokenを一緒に照合します。

失敗を再発させない記録とテスト

OAuth scopeの変更は、method単位で必要理由を記録します。アプリのmanifestやOAuth設定ではbot/userのscopeを分け、各scopeについて使うmethod、必要な操作、対象resourceを書きます。アプリ全体で万能な「必要scope一覧」を使い回すと、不要な権限を要求したり、token typeと機能が不整合になったりします。

テストでは実token値をfixture、console、CI logへ書かず、必要なscopeの集合、token type、resource accessをfake credentialや隔離workspaceで検証します。統合テスト用workspaceを使う場合も、本番ユーザーへメッセージを送らないこと、テストデータの削除範囲が明確であることを確かめます。scope変更時には、新規installだけでなく既存installでの再認可要否を公式のapp lifecycle情報から確認してください。

長期運用では、App Manifestの変更、OAuth要求scope、workspaceの再認可、発行tokenの更新を一組の変更記録として管理します。Scope追加を済ませた人と、実際にAPI requestを発行する実行環境が別の場合、後者のsecret storeに新tokenが反映されたかまで確認します。作業完了条件は「設定にscope名が見える」ではなく、「対象workspace・対象token type・対象methodの再試験が成功し、秘密値が露出していない」です。

最終チェックリスト

  • 失敗methodとresponseのerrorを特定した

  • needed/providedはscope名だけを安全に記録した

  • methodの公式要件とtoken typeを照合した

  • bot/user/workflow tokenを区別した

  • Appと対象workspaceのinstall状態を確認した

  • scope追加後に再認可が必要かを確認した

  • requestが古いtokenや別workspaceのtokenを使っていない

  • user tokenへ切り替える場合、代理操作の意味を確認した

  • 最小権限でテストし、secretを記録していない

  • API methodが通っただけで、不要なscopeを残していない

次に行うこと

対象requestのmethod名、error、needed、provided、token type、workspace install状況を、秘密値なしで一覧にしてください。次に該当methodのSlack公式referenceで必須scopeと受け付けるtoken typeを照合し、権限設定を変える前にscope追加先と再インストール要件を確定します。workspace管理者権限が必要なら、必要scopeと再認可理由を添えて依頼します。実際のapp設定やrequestを見ていないため、この手順を使って環境固有の原因を特定してください。

Sources