outreach API 401 invalid_token mid-day - agent's OAuth app got its scopes reduced

TL;DR

The OAuth app's scopes were reduced mid-day, so the access credential no longer covers the calls the agent makes. Pause the automation, have a human re-authorize the app with the full scope set in the Outreach app settings, and only resume after a scope check passes. Do not retry the failed calls; they will keep 401ing.

outreach API 401 invalid_token mid-day  -  agent's OAuth app got its scopes reduced

Steps

1. Stop the agent's Outreach calls immediately. Retrying with a scope-deficient credential just burns the run and can look like abuse. Expected: the 401 stream stops.

2. Open the OAuth app's settings in Outreach and compare the currently granted scopes against the scopes the agent's calls need. Expected: you can name the missing scopes.

3. Have a human re-authorize the app with the full scope set. This is a human step: scope grants belong to the account owner, not the agent. Expected: the app shows the complete scope list again.

4. Add a startup scope check to the agent: before the first real call, hit a cheap endpoint and verify the response is not a scope-related 401. Halt with a clear alert if it is. Expected: the next scope reduction pages a human in seconds instead of failing all day.

5. Resume the run only after the scope check passes, and replay the calls that failed during the outage window. Expected: the backlog processes normally with no further 401s.

Use this when

• A working Outreach session starts returning 401 invalid_token with no credential change on the agent side.
• An admin recently edited the OAuth app's scopes.
• Only some endpoints 401 while others still work (a scope gap, not a dead credential).

Not for this skill when

• The 401 comes from an expired credential the agent can refresh itself through its normal refresh flow.
• The app was fully revoked or deleted (that needs reinstallation, not re-scoping).
• The error is a 403 on a specific action (a permission, not a scope).

Variant phrasings

• "outreach 401 mid day scopes reduced"
• "outreach invalid_token oauth scopes changed"
• "outreach api 401 after admin changed app"

Why it happens

Outreach OAuth scopes are granted to the app by an admin and can be reduced at any time without notifying connected integrations. The existing access credential keeps working for the remaining scopes but 401s on anything outside them. From the agent's side it looks like the credential died mid-day; the real change was on the app's scope list.

Edge cases

• Scope reductions can be partial and silent for hours if the agent only calls the still-permitted endpoints early in the day.
• Re-authorization must come from someone with admin rights on the Outreach account. The agent cannot grant its own scopes.
• Log which scopes the startup check verified, so the next incident starts with a known-good baseline.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst9khDOeC55Pd3sFYdKAg