EXPLAINER

OAuth for AI Agents

OAuth lets a user grant your agent app limited access to a provider without sharing their password. Your server holds tokens; the model only triggers tools that use those tokens under your policy.

Short answer: OAuth for agents means user consent, access vs refresh tokens, server-side storage, least privilege — the model is never the OAuth client.

What is it?

OAuth 2.0 is how a user authorises your application to call an API (Gmail, calendar, GitHub) without giving you their password. For agents, OAuth still happens between the user, your server, and the provider. The LLM is not a party to the handshake; it only requests tools that your server may execute if tokens and policy allow.

Why it matters

Agents amplify token risk: a manipulated prompt might try to trigger a send-mail tool. Correct OAuth storage and scopes limit blast radius (Permissions and Security for AI Integrations).

How to do it

  1. Register an OAuth client with the provider; keep the client secret on the server.
  2. Redirect the user to the consent screen with explicit scopes.
  3. Receive an authorization code; exchange it for access and refresh tokens.
  4. Store tokens encrypted at rest, keyed by user id.
  5. Use access tokens for API calls; refresh when expired; revoke on logout.
  6. Map each agent tool to the minimum scopes it needs.
  7. Separate "user connected Google" (OAuth) from "model may call tool" (your authZ policy).

Example

Scopes for a read-only mail summariser might include Gmail readonly only (a restricted scope with extra review requirements; see Gmail API Scopes and Verification). A draft tool might need compose scope but still leave final send to a human. Document the scopes in your privacy policy (AI Privacy and Security: What to Know Before You Paste Data).

When to use it

Use OAuth when calling APIs on behalf of a user. Use a service account or API key only for non-user systems you fully control — and still do not give those credentials to the model.

Practical notes

Implementation details that prevent outages: handle refresh-token rotation when providers invalidate old refresh tokens, clock-skew when validating JWTs, and missing scopes when you add a new tool later (re-consent flow). Use PKCE for public clients; keep confidential clients on the server. Separate "connect account" UX from "enable agent tool" UX so users understand both steps. Monitor auth error rates distinctly from model error rates. When acting for a user, stamp tool logs with the user id and OAuth client id used. Read API Authentication: Keys, Sessions and OAuth for how OAuth sits beside API keys and sessions, and Permissions and Security for AI Integrations for approval gates after tokens exist. Work through one real request end to end, write down the failure modes you observed, and add a regression test so the next change does not silently drop validation, auth, or logging. Prefer boring, reviewable code over a clever abstraction until the second or third product needs the same pattern. Work through one real request end to end, write down the failure modes you observed, and add a regression test so the next change does not silently drop validation, auth, or logging. Prefer boring, reviewable code over a clever abstraction until the second or third product needs the same pattern.

Common mistakes

  • Putting refresh tokens in localStorage.
  • Requesting "full access" scopes for demos that never get tightened.
  • Letting the model choose arbitrary scopes dynamically.
  • Logging Authorization headers.