OAuth for AI agents: how agents sign in to your apps

OAuth is the "Sign in with Google"-style flow that lets an AI agent act on your apps without ever handling your password: you approve access once in your browser, the app issues a token for the permissions on the consent screen, and the agent's integration uses that token for every action. The approved grant can be narrow or broad. You can revoke it from the provider's security settings.

Why agents shouldn't use your password

A password or app password is a standing credential that can end up in a local config file. An OAuth token is tied to one integration and one approved grant, and the provider can invalidate it when you revoke that grant. OAuth does not guarantee least privilege: the consent screen may still request broad access. Any agent setup that asks you to paste your actual password into a config file is a red flag.

How the OAuth flow works for an agent

You click connect, the app (Google, Notion, Slack…) shows its own consent screen listing what's being requested, and on approval it sends a token back to the integration, not to the model. From then on, every tool call the agent makes is authenticated with that token, and the integration silently refreshes it when it expires. The model itself never sees a credential.

The three pieces you get back

A completed OAuth flow hands the integration three things, and knowing which is which explains most auth failures:

The access token is the one that expires constantly, which is why anything running longer than an hour needs token refresh working in the background.

Scopes: what the agent is allowed to do

Scopes are the permissions on the token. "Read email" and "send email" are separate scopes in Gmail, for example. An agent can only call actions its token's scopes allow; anything else fails at the provider, no matter what the agent tries. This is also why a tool occasionally fails even though the connection is healthy: the account or plan simply doesn't include that permission.

A scope can also cover an entire service. ClawLink's Gmail connection requests https://mail.google.com/, which covers the full mailbox so its tools can search, read, draft, send, forward, and manage labels. Review the actual consent screen instead of assuming that an OAuth connection is narrow.

Scopes are fixed when you approve the consent screen. Adding a capability later means a new consent flow, not a code change: a token issued for read access cannot be talked into writing, whatever the agent tries.

Reading the error you actually got

Auth failures fall into a few buckets, and they need opposite responses:

• 401 Unauthorized means the token is bad. Usually it expired and refresh will fix it. If refresh also fails, the connection needs re-authorising.
• 403 Forbidden means the token is valid but not allowed. Either the scope is missing, or the account cannot reach that specific resource. Refreshing changes nothing. Worth checking before assuming a scope gap: a 403 can also come from a malformed or placeholder id in the request rather than the token.
• invalid_grant on refresh means the refresh token itself is dead. The user revoked access, changed their password, or an admin removed the app. Only a new consent flow recovers it.

The practical rule: retry a 401 once after refreshing, never retry a 403.

Who holds the token

If you wire up an integration yourself, the token usually ends up in a local config file. That works, but you own its storage, refresh logic, and revocation story. A hosted app connector holds tokens server-side, encrypted, so the agent's machine never stores app credentials at all.

That's ClawLink's model: hosted OAuth for every app that supports it, encrypted credential storage, and disconnect-anytime from the dashboard. Details on the security page. For apps that only offer API keys, the hosted setup walks you through those too. See is it safe to connect Gmail to an AI agent? for the trust checklist.

FAQ

Keep reading