AuthAPIError Invalid Refresh Token Already Used | Fix

What AuthAPIError Invalid Refresh Token Already Used Means

When an auth library raises the message “authapierror invalid refresh token already used”, it is telling you that the refresh token your code sent cannot be accepted anymore. The server already consumed that token during a previous refresh, or the token record no longer exists in the auth store.

Many modern providers treat refresh tokens as one time secrets. Each time the client uses a refresh token, the server issues a new access token and a new refresh token, then marks the old refresh token as invalid. If the client keeps using that old token, the server responds with an error instead of extending the session.

In short, this error means the server no longer trusts the token supplied by the client. To keep the account safe, the provider refuses to refresh the session and expects a fresh login.

How Refresh Tokens Work In Modern Auth Flows

To solve the problem cleanly, it helps to know how refresh tokens fit into an auth flow. Most systems issue two main credentials after a user signs in: a short lived access token and a longer lived refresh token. The access token goes out with API calls, while the refresh token stays in a cookie or secure store.

When the access token expires, the client uses the refresh token once to ask for a new access token and a new refresh token. Many providers use refresh token rotation, which means every successful refresh replaces the old refresh token with a new one. The previous token is now invalid and must never be sent again.

Here is a simple view of that cycle that often leads to an “invalid refresh token already used” error when things get out of sync:

1. User signs in — The server returns an access token, a refresh token, and sets any auth cookies.
2. Client stores tokens — Your app writes tokens to secure cookies, memory, or a storage helper from the auth SDK.
3. Access token expires — A later request fails with 401, or the SDK notices the expiry time.
4. Client sends refresh token — The client calls the auth endpoint with the current refresh token.
5. Server rotates tokens — A new access token and refresh token are issued, and the old refresh token is marked invalid.
6. Old token is reused — A stale tab, another device, or buggy code sends the previous refresh token again, which causes the error.

In many cases you will also see the raw string “authapierror invalid refresh token already used” near stack traces from Supabase or other GoTrue based auth servers. The wording may vary a little between libraries, but the meaning is the same across platforms.

Common Causes Of This Invalid Refresh Token Error

The message may look mysterious at first, yet the root causes tend to fall into a few patterns. Understanding these patterns makes it easier to fix the log noise and the user impact.

• Stale browser tabs or devices — A user signs in on several tabs or devices, one of them refreshes the session, and another still holds the old refresh token.
• Copied auth data between machines — A developer copies a config file or auth JSON from one environment to another, so two instances try to reuse the same refresh token.
• Cleared or mismatched cookies — Cookies on the client get cleared or changed while the server still expects a newer token. When the old cookie value is sent, the server cannot match it to any stored token.
• Manual refresh calls — Custom code calls a refresh endpoint directly instead of using the official helper. If that code runs more than once, it may reuse an old refresh token.
• Long idle sessions — A user leaves a session open for days. In some systems, extra security rules or rotation policies invalidate the refresh token even if it was never used.
• Library or config mismatch — Using different versions of the auth client on different parts of an app, or mixing cookie settings, can lead to clients sending tokens that no longer match what the server expects.

Because refresh tokens often live in HTTP only cookies, it is easy for multiple parts of a stack to end up reading and sending different cookie values. The result is a refresh request with a token that used to be valid but no longer exists on the server side.

Fixing An Authapierror Invalid Refresh Token Already Used In Your App

You usually do not need to restart servers or wipe databases when you meet this error. The main goal is to push the client back into a clean state, then make sure your code handles future refresh attempts in a safe way.

Reset The Session For The Affected User

Quick reset: When you see the error for one user, the fastest remedy is to clear their session and have them sign in again. That simple round trip gives them a fresh set of tokens and stops the loop.

• Call the sign out method — Use the official SDK call, such as a signOut helper, to clear auth cookies on the client and on the server.
• Redirect to the login page — After sign out, send the user to a plain login route so they can start a new session.
• Handle the next login cleanly — Be sure that any old tokens kept in memory are dropped when a new login completes.

Let Your Auth Library Handle Refresh Logic

Most provider SDKs include helpers that manage token refresh, cookie updates, and storage. Custom refresh code that calls auth endpoints by hand is more likely to reuse an old token and cause the error.

• Use built in session helpers — Rely on functions such as getSession or middleware utilities instead of home grown wrappers.
• Avoid manual refresh endpoints — Remove direct calls to low level refresh URLs from frontend code when a higher level helper exists.
• Check for duplicate refresh calls — Make sure hooks and effects in your React, Vue, or Remix code do not trigger the same refresh logic twice for one event.

Check Cookie And Storage Settings

Misaligned cookie settings are another frequent source of this auth error. If the browser and the server apply different rules for domain, path, or same site mode, a client may send a refresh token that does not match the server’s latest record.

• Review cookie domain and path — Confirm that auth cookies are set on the right domain and path so that frontend and backend read the same ones.
• Confirm same site and secure flags — Cookies that only flow on one type of request can leave stale values in some parts of an app.
• Audit storage layers — If you also keep tokens in local storage or memory, trim that down so the SDK stays in charge of token state.

When cookies, storage, and SDK behavior line up, refresh token rotation runs in a smooth cycle instead of breaking with “token already used” messages.

When To Log Out Users And Ask For Fresh Sign-In

You will sometimes see this error due to a real security event, such as a stolen cookie or a user who copied auth files between shared servers. In those cases it is safer to end the session than to try to rescue a token that the server already rejected.

Risk based approach: Treat every “invalid refresh token already used” for a real user account as a hint that token state might be out of your control. The clean response is to sign the user out and send them through a normal login flow where multi factor checks and device trust rules still apply.

• Show a clear session message — Tell the user that their session expired and that a new login is needed to keep the account safe.
• Log enough context — Record user ID, IP, and user agent in structured logs so you can review patterns later without exposing secrets.
• Watch for repeated events — If the same account hits the error again and again, review whether they use shared machines or scripted clients.

For high risk apps, you might also add rate limits on refresh attempts so that repeated failures do not flood logs or hint at brute force tests against your auth endpoints.

Hardening Token Storage And Rotation

Once the immediate errors are under control, it pays to tighten the general design of token storage and refresh logic so this class of bug stays rare. The aim is to have one clear source of truth for tokens and one simple path for refresh.

• Keep tokens off disk where possible — Prefer HTTP only cookies or in memory storage over files that developers might copy between hosts.
• Avoid sharing auth.json across machines — Tools that keep refresh tokens in config files should not be copied between local and remote setups.
• Limit parallel sessions — Decide whether your app should allow many active sessions per user, then configure the auth provider to match that policy.
• Upgrade auth libraries promptly — Stay close to current versions of your auth SDK so you receive fixes for edge cases in refresh logic.
• Handle 401 and 400 codes consistently — When the server rejects a refresh with status 400 or 401, clear local session state and route the user to login.

A short design document that explains where tokens live, which module owns refresh logic, and how many sessions a user may have at once will also help new team members avoid mistakes. When those rules stay stable, logging and monitoring become clearer, and odd “token already used” spikes stand out as real incidents instead of background noise.

Quick Reference Table For Debugging

The table below summarizes common symptoms, likely causes, and practical fixes for “refresh token already used” style errors across auth providers.

Send us your feedbackTell us what you thought about this post

Name * Email *

Your comment *

Quick check — what is …? *

Send feedback