Skip to Content
How-to guidesHow-to guidesReauth a platform

Reauth a platform

OAuth tokens expire. When that happens, AgentValet flips the platform’s health_status to reauth_needed and your agent’s next call to that platform returns 401 with a specific reason.

How you’ll notice

Three places:

  1. /platforms — the card shows a red reauth_needed badge and a Reauth button instead of Connect / Test.
  2. Audit log — failed calls have result: error with reason reauth_needed in metadata.
  3. The agent itself — its use_platform call gets back a clear error that includes a report_hint, so the agent can surface “Looks like {platform} needs to be reauthed” to whoever is talking to it.

How to reauth

/platforms → click Reauth on the affected card.

For OAuth platforms, the Nango popup opens with the same auth flow as the initial Connect. Sign in, approve, and the new token gets stored. The card flips back to active.

For API-key platforms, the connect form opens with the existing field labels. Paste a new key.

Lazy refresh — usually you won’t have to do this manually

For most OAuth platforms, AgentValet attempts a token refresh automatically on the first 401 from upstream — Nango stores the refresh token and exchanges it transparently. If that succeeds, the agent’s call goes through, you never see reauth_needed, and the audit log notes that a refresh happened.

You only need to manually reauth when:

  • The refresh token itself has expired (usually 90+ days idle)
  • The user revoked AgentValet’s access on the platform’s side
  • The platform changed its OAuth scopes and you need to re-consent

What’s affected

While a platform is in reauth_needed, every agent with a scope on that platform fails its next call there. Other platforms are unaffected — the issue is per-platform-connection.

Next

Suggest a new platformApprove in the dashboard