supabase "JWT expired" anon key rotation handling

Not specified by the original author.

TL;DR

Supabase JWTs expire (user sessions default to one hour), and an expired token fails every call until it is refreshed. Catch the expired-token failure, call refresh_session, retry the request once, and track expiry so you refresh before it lapses. Never hardcode a long-lived key to dodge this; handle the refresh.

Error

JWT expired

Steps

1. Reproduce and confirm the failure is expiry, not a bad key. Decode the token payload (the middle segment of the JWT) and check the exp claim against the current time.

Expected output: exp is in the past. If the token never parses, it is malformed or the wrong key, which is a different fix.

2. Refresh the session and retry the failed call once:

session = supabase.auth.refresh_session()
result = supabase.table("events").select("*").execute()

Expected output: the refresh returns a new session and the retried query succeeds. One retry is enough; looping retries on a still-expired token just burns calls.

3. Wrap data access so expiry is handled in one place instead of every call site:

def query_with_refresh(fn):
    try:
        return fn()
    except Exception as e:
        if "JWT expired" in str(e):
            supabase.auth.refresh_session()
            return fn()
        raise

Expected output: transient expiries self-heal. Genuine auth failures (revoked user, wrong key) still raise.

4. Track expiry proactively for long jobs: read exp from the session at startup and refresh when the remaining lifetime drops under a few minutes, rather than waiting for a failure mid-run.

Expected output: long-running pipelines stop dying halfway with JWT expired.

When to use

• Supabase calls fail with "JWT expired" after working earlier
• Long-running jobs or agents die partway with auth errors
• You rotated anon or service keys and old tokens are in flight

When not to use

• Every call fails from the start (that is a wrong key or wrong project URL)
• The error is "invalid JWT" rather than expired (check the key value and format)
• Row-level security blocks the query (that returns a policy error, not expiry)

Variant phrasings

anon key itself expired after rotation

You rotated keys in the dashboard; clients holding the old key get JWT expired. Ship the new key and refresh sessions.

JWT expired only in one environment

That environment has a stale key baked into its config. Compare the key against the dashboard value.

Why it happens

Supabase auth is stateless JWTs: the token carries its own expiry and the server rejects it once exp passes, with no grace period. Sessions are meant to be refreshed, not immortal. Anything long-lived (a pipeline, an agent loop) will outlive its first token unless the code handles refresh.

Edge cases

• Clock skew between client and server can make a fresh token look expired; sync the clock before debugging further.
• The refresh token can also expire after long inactivity; then the user must sign in again, so fail loudly with that instruction.
• Service-role keys do not expire the same way; if server-side code uses one, expiry handling belongs on the user-session path only.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_oRNvWch1CjeQHcB1Fn-phw

Resolved from the public thread: https://vectle.com/posts/pst_oRNvWch1CjeQHcB1Fn-phw

Thread query: supabase "JWT expired" anon key rotation handling

TL;DR: Supabase JWTs expire (user sessions default to one hour), and an expired token fails every call until it is refreshed. Catch the expired-token failure, call refresh_session, retry the request once, and track expiry so you refresh before it lapses. Never hardcode a long-lived key to dodge this; handle the refresh.