Token refresh for AI agents: keeping long-running tasks authenticated

Token refresh is the process of exchanging a long-lived refresh token for a new access token once the current one expires, so an agent can keep acting on an app without asking you to sign in again. Access tokens are short-lived by design, typically about an hour, so any agent task that runs longer than that will hit an expired token unless something refreshes it in the background.

Key takeaways

• Refresh exchanges a long-lived refresh token for a new short-lived access token, so an agent keeps working without a new sign-in.
• Access tokens are short-lived by design, often about an hour, so any longer task crosses an expiry boundary.
• Get both mechanisms: refresh proactively before expiry, and keep a 401 handler as a backstop.
• Refresh token rotation is the classic multi-worker bug. Concurrent refreshes can invalidate each other and kill the connection.
• invalid_grant is terminal. Only a new consent flow recovers it.
• A hosted connector does the refresh for the user, so the agent never holds a credential or writes refresh code.

Why do tokens expire in the middle of a task?

OAuth providers issue two things at the end of a consent flow: a short-lived access token used on every API call, and a longer-lived refresh token used only to mint new access tokens.

The refresh happens between the server and the provider. The agent never holds either token, and a 401 is the backstop if the refresh is late.

Typical access token lifetimes:

The lifetimes come from each provider's own documentation, checked on 16 September 2026: Google, Microsoft, Slack and Notion. Treat them as defaults, because an administrator can shorten them.

An agent that triages a mailbox for ninety minutes, or a scheduled job that runs unattended overnight, will cross at least one expiry boundary. The API call that crosses it returns 401 Unauthorized, and an agent without refresh logic simply fails, usually in a way that looks like a permissions bug rather than an expiry.

Reactive or proactive refresh?

There are two ways to handle expiry, and the difference matters more than it looks.

Reactive refresh waits for a 401, exchanges the refresh token, and retries the original call. It is simple and it wastes no refreshes, but every expiry costs one failed round trip, and the retry has to be genuinely idempotent or you risk sending the same message twice.

Proactive refresh checks the expiry timestamp before each call and refreshes early if the token is close to the end of its life. Calls never fail for expiry, at the cost of tracking expiry per connection.

Production setups generally do both: refresh proactively, and still catch the 401 for the cases where a token was revoked or invalidated early.

What does a production refresh loop do?

Three mechanisms, and production setups run all three.

• Proactive refresh. Renew the token when it reaches a set fraction of its lifetime, so a call never starts on a token about to expire. Scalekit's production guide suggests refreshing at 70% to 80% of the token's lifetime, checked on 16 September 2026.
• Reactive fallback. If a call still returns 401, refresh once and retry. The retry must be safe to repeat, or a write can be duplicated.
• Startup validation. Before a long or unattended run, confirm each connection's token is still valid, so the job does not fail an hour in on a dead credential.

This is also where a credential broker earns its place. Keeping the refresh tokens in a vault the agent cannot read means a compromised agent cannot exfiltrate them, which is the design Auth0 describes for its Token Vault, checked on 16 September 2026.

A connection health check on 16 September 2026. needs_reauth turns true when a refresh fails and the account must reconnect.

What are the four ways refresh breaks?

Expiry is the easy part. These are the failures that cost real debugging time.

1. Refresh token rotation. Some providers issue a new refresh token every time you refresh and immediately invalidate the old one. If you store the new one and the write fails, or two workers refresh concurrently and one overwrites the other, the connection is dead and the user has to reconnect. Concurrent refresh is the classic multi-worker bug here.
2. invalid_grant. The catch-all error when a refresh token no longer works: the user revoked access, changed their password, the token went unused past the provider's idle window, or an admin removed the app. It is not retryable. The only fix is a fresh consent flow.
3. Confusing 401 with 403. A 401 means the token is bad and refresh may help. A 403 means the token is fine but lacks the scope, or the account cannot reach that resource. Retrying a 403 with a refreshed token fails forever. See OAuth for AI agents on scopes.
4. Silent failure in unattended runs. When a scheduled agent hits a dead connection at 3am, nobody sees the error. Without a stored state flag and a way to surface it, the first sign of trouble is missing work.

Who should own the refresh loop?

If you wire up an integration yourself, you own all of the above, once per provider, and each provider does it slightly differently. That is the real cost: not writing one refresh function, but maintaining a dozen of them against APIs that change without asking.

A hosted app connector centralises it. Refresh happens outside the agent's process, and the agent's machine never stores app credentials at all. The agent just calls tools and they work.

ClawLink's model follows the same split as its credential storage. For most OAuth apps, Composio runs the hosted flow and holds the provider's access and refresh tokens as our subprocessor, so refresh happens upstream of the agent. For the few apps connected through a vendor's own MCP server, ClawLink holds those tokens itself, encrypted, and refreshes them. Either way, ClawLink stores an opaque reference to the connection. When a connection genuinely cannot be recovered, ClawLink marks it as needing re-authentication rather than failing silently, and the failed tool call comes back with a reason and a reconnect path, so the agent can tell the user what to do instead of retrying a dead token in a loop. The split is documented in the trust center.

What changed in this review

This page was refreshed on 16 September 2026. It added a key-takeaways block and a production-refresh-loop section covering proactive refresh at 70 to 80 percent of lifetime, the reactive 401 fallback, and startup validation, and added source links and check dates to the provider lifetime table. The credential-storage wording now follows the trust center's split.

FAQ

Keep reading