How to Implement Token Refresh and Rotation for Python API Authentication with Authlib

Access tokens expire by design -- usually within minutes. Without a refresh mechanism, every expiration forces the user to re-authenticate from scratch, which is unacceptable for long-running scripts, background services, and Python web applications that consume APIs. Authlib, the comprehensive Python OAuth library, provides both automatic and manual token refresh built into its OAuth2Session, along with callback hooks for persisting new tokens and detecting rotation violations. This guide covers each of these patterns with working code, verified against the Authlib Client API References and the relevant OAuth 2.0 RFCs.

The OAuth 2.0 token lifecycle follows a predictable pattern defined in RFC 6749, Section 1.5: the client obtains an access token and a refresh token during the initial authorization. The access token is short-lived (typically 15 to 60 minutes) and used for API calls. When it expires, the client sends the refresh token to the authorization server's token endpoint and receives a fresh access token -- and in secure configurations, a new refresh token as well. Authlib handles this lifecycle at the session level, so your application code can focus on making API calls without managing token state manually.

Why Token Refresh Matters

Short-lived access tokens are a security feature, not a nuisance. If a token is stolen, the attacker has a narrow window to use it. But this protection creates a practical problem: an application that makes API calls over a span of hours or days needs a reliable way to obtain new tokens without user interaction. The refresh token solves this by acting as a long-lived credential that can be exchanged for a new access token at any time.

The catch is that refresh tokens themselves must be stored securely, rotated after each use, and revoked when suspicious activity is detected. As RFC 9700 (Best Current Practice for OAuth 2.0 Security, published January 2025) puts it, refresh tokens for public clients must be either sender-constrained or use refresh token rotation. For confidential clients, RFC 6749 already mandates that refresh tokens can only be used by the client for which they were issued.

Setting Up Authlib's OAuth2Session

Authlib provides OAuth2Session for synchronous code (built on Requests) and AsyncOAuth2Client for asynchronous code (built on HTTPX). Both share the same API for token management. Authlib requires Python 3.9 or later. Install it with pip:

copypip install authlib requests

# For async support:
# pip install authlib httpx

# Verify your version is 1.6.9+ (critical security patches):
# python -c "import authlib; print(authlib.__version__)"

Create a session with your OAuth 2.0 credentials. The token_endpoint parameter is the key to enabling automatic refresh -- when it is set, Authlib knows where to send refresh requests. According to the Authlib Client API References, the OAuth2Session constructor accepts token_endpoint, update_token, and leeway among its keyword arguments.

copyfrom authlib.integrations.requests_client import OAuth2Session

client_id = "your-client-id"
client_secret = "your-client-secret"
token_endpoint = "https://auth.example.com/oauth/token"
authorization_endpoint = "https://auth.example.com/oauth/authorize"

session = OAuth2Session(
    client_id,
    client_secret,
    token_endpoint=token_endpoint,
)

Automatic Token Refresh

When you provide token_endpoint during session creation, Authlib automatically refreshes the access token before it expires. As the official OAuth 2 Session documentation states, the token will be refreshed 60 seconds before its expiry time to avoid clock skew issues. You can adjust this buffer with the leeway parameter -- for example, setting leeway=120 triggers the refresh two minutes early instead of one.

copyfrom authlib.integrations.requests_client import OAuth2Session

def update_token(token, refresh_token=None, access_token=None):
    """Callback: persist the new token to your database.

    Args:
        token: The new token dict from the authorization server.
        refresh_token: The refresh_token value from the OLD token
                       (use to locate the existing DB record).
        access_token:  The access_token value from the OLD token
                       (used when token was refreshed via client_credentials).
    """
    if refresh_token:
        # Locate the old token record by its refresh_token value
        item = db.find_token_by_refresh(refresh_token)
    elif access_token:
        # For client_credentials grant, locate by access_token
        item = db.find_token_by_access(access_token)
    else:
        return

    # Update the record with the new token values
    item.access_token = token["access_token"]
    item.refresh_token = token.get("refresh_token")
    item.expires_at = token["expires_at"]
    item.save()

session = OAuth2Session(
    "your-client-id",
    "your-client-secret",
    token_endpoint="https://auth.example.com/oauth/token",
    token_endpoint_auth_method="client_secret_basic",
    update_token=update_token,  # Called on every refresh
)

# Load an existing token (e.g., from your database)
session.token = {
    "access_token": "current-access-token",
    "refresh_token": "current-refresh-token",
    "token_type": "Bearer",
    "expires_at": 1710600000,  # Unix timestamp
}

# Make API calls -- token refreshes transparently
response = session.get("https://api.example.com/v1/data")
print(response.json())

The update_token callback fires every time Authlib refreshes the token. This is your hook for persisting the new token to a database, file, or secrets manager. Without this callback, the refreshed token would only exist in memory and would be lost if the application restarts.

The update_token Callback (Correct Signature)

A common point of confusion in tutorials and blog posts is the update_token callback signature. The correct signature, as shown in the Authlib Web OAuth Clients documentation, the Flask integration docs, and the HTTPX integration docs, is:

copydef update_token(token, refresh_token=None, access_token=None):
    """
    Correct Authlib update_token signature.

    - token:          The NEW token dict (contains access_token,
                      refresh_token, expires_at, etc.)
    - refresh_token:  The OLD refresh_token string (use to find
                      the existing record in your database)
    - access_token:   The OLD access_token string (used for
                      client_credentials grant lookups)
    """
    pass

The refresh_token keyword argument gives you the string value of the old refresh token that was used to obtain the new one. This is your database lookup key: find the existing record by this value, then overwrite it with the new token's fields. The access_token keyword argument serves the same purpose for client_credentials grants, where there is no refresh token but the old access token can be used to locate the record.

For framework integrations (Flask, Django), Authlib also supports a signal-based approach. The Flask integration provides a token_update signal with the same parameter signature plus a name parameter identifying the OAuth provider:

copy# Flask signal-based approach (alternative to passing update_token directly)
from authlib.integrations.flask_client import token_update

@token_update.connect_via(app)
def on_token_update(sender, name, token,
                    refresh_token=None, access_token=None):
    if refresh_token:
        item = OAuth2Token.find(name=name, refresh_token=refresh_token)
    elif access_token:
        item = OAuth2Token.find(name=name, access_token=access_token)
    else:
        return

    item.access_token = token["access_token"]
    item.refresh_token = token.get("refresh_token")
    item.expires_at = token["expires_at"]
    item.save()

Manual Token Refresh

Sometimes you need explicit control over when the refresh happens -- for example, if you want to refresh proactively at application startup or on a timer rather than waiting for an API call to trigger it. Authlib supports this with the refresh_token() method, as documented in the OAuth 2 Session guide.

copyfrom authlib.integrations.requests_client import OAuth2Session

session = OAuth2Session(
    "your-client-id",
    "your-client-secret",
)

# Load the previous token from storage
previous_token = load_token_from_database()

# Explicitly refresh before making any calls
new_token = session.refresh_token(
    "https://auth.example.com/oauth/token",
    refresh_token=previous_token["refresh_token"],
)

# Save the new token
save_token_to_database(new_token)

# Now use the session with the fresh token
session.token = new_token
response = session.get("https://api.example.com/v1/data")
print(response.json())

Persisting Tokens Across Restarts

A token that only exists in memory is lost when your script ends or your server restarts. For production applications, you need to persist tokens to a durable store and reload them at startup. Here is a pattern using a simple JSON file with restricted permissions for local development, and a database for production:

copyimport json
import os
from pathlib import Path
from authlib.integrations.requests_client import OAuth2Session

TOKEN_FILE = Path(".tokens.json")

def load_token():
    """Load token from file (dev) or database (prod)."""
    if os.environ.get("ENV") == "production":
        return db.get_token(user_id=current_user.id)
    if TOKEN_FILE.exists():
        return json.loads(TOKEN_FILE.read_text())
    return None

def save_token(token, refresh_token=None, access_token=None):
    """Persist token to file (dev) or database (prod).

    Uses the correct Authlib callback signature with
    refresh_token and access_token keyword arguments.
    """
    if os.environ.get("ENV") == "production":
        if refresh_token:
            item = db.find_token_by_refresh(refresh_token)
        elif access_token:
            item = db.find_token_by_access(access_token)
        else:
            return
        item.access_token = token["access_token"]
        item.refresh_token = token.get("refresh_token")
        item.expires_at = token.get("expires_at")
        item.save()
    else:
        TOKEN_FILE.write_text(json.dumps(token, indent=2))
        # Restrict file permissions (Unix/macOS)
        TOKEN_FILE.chmod(0o600)

session = OAuth2Session(
    "your-client-id",
    "your-client-secret",
    token_endpoint="https://auth.example.com/oauth/token",
    update_token=save_token,
)

# Restore the previous token on startup
existing_token = load_token()
if existing_token:
    session.token = existing_token

Token Rotation and Reuse Detection

Token rotation is a security pattern where the authorization server issues a new refresh token every time the old one is used, and immediately invalidates the old one. This means each refresh token is single-use. RFC 6819, Section 5.2.2.3 codifies this as "Refresh Token Rotation" and recommends it as a countermeasure to token theft. The RFC 9700 (January 2025) goes further, stating that refresh tokens for public clients "MUST be sender-constrained or use refresh token rotation."

If an attacker steals a refresh token and tries to use it after the legitimate client has already exchanged it, the server detects the reuse and can revoke the entire token family -- invalidating all access for that user until they re-authenticate. As Auth0's documentation on refresh token rotation explains, when a previously-used refresh token is sent to the authorization server, the server immediately invalidates the entire chain of tokens descending from the original grant.

From the client side, handling rotation is straightforward: every time you receive a new token response, check whether the refresh_token value has changed and persist the updated value. Authlib's update_token callback gives you the tools to do this automatically.

copydef save_token_with_rotation_check(token,
                                    refresh_token=None,
                                    access_token=None):
    """Persist token and detect rotation.

    Uses the correct Authlib callback signature.
    The refresh_token arg is the OLD value; token["refresh_token"]
    is the NEW value returned by the authorization server.
    """
    new_rt = token.get("refresh_token")

    if refresh_token and new_rt and refresh_token != new_rt:
        # The server rotated the refresh token.
        # The old one (refresh_token) is now invalid.
        print("Refresh token rotated by server.")

    # Locate and update the existing record
    if refresh_token:
        item = db.find_token_by_refresh(refresh_token)
    elif access_token:
        item = db.find_token_by_access(access_token)
    else:
        return

    item.access_token = token["access_token"]
    item.refresh_token = new_rt
    item.expires_at = token.get("expires_at")
    item.save()

session = OAuth2Session(
    "your-client-id",
    "your-client-secret",
    token_endpoint="https://auth.example.com/oauth/token",
    update_token=save_token_with_rotation_check,
)

If your provider does not rotate refresh tokens, the same refresh token remains valid across multiple uses. In that case, you still need to store it securely, but you do not need the rotation detection logic. Check your provider's documentation to confirm their rotation policy -- providers like Auth0 and Okta offer configurable rotation with grace periods for handling network failures.

Error Handling: What to Do When Refresh Fails

The article so far has shown the happy path: the refresh token is valid, the server responds with a new token pair, and the callback persists it. In production, refreshes fail for a range of reasons, and the failure mode determines whether your application should retry, re-authenticate, or alert an operator. Authlib raises OAuthError (or its subclasses) when the authorization server returns an error response during token refresh, so you can catch these at the session level.

The authorization server returns invalid_grant when the refresh token is expired, revoked, or has already been used (in rotation scenarios). This is the error defined in RFC 6749, Section 5.2. When you receive it, the refresh token is dead -- retrying with the same token will produce the same error. The only recovery path is a full re-authorization flow (redirecting the user back through the consent screen, or prompting for credentials again in a service context).

copyimport logging
import time

import requests
from authlib.integrations.requests_client import OAuth2Session
from authlib.common.errors import AuthlibBaseError

log = logging.getLogger(__name__)

session = OAuth2Session(
    "your-client-id",
    "your-client-secret",
    token_endpoint="https://auth.example.com/oauth/token",
    update_token=save_token,
)
session.token = load_token_from_database()

try:
    response = session.get("https://api.example.com/v1/data")
    response.raise_for_status()
except AuthlibBaseError as e:
    if "invalid_grant" in str(e):
        # Refresh token is dead -- force re-authentication
        clear_stored_token(user_id=current_user.id)
        redirect_to_login()
    elif "invalid_client" in str(e):
        # Client credentials are wrong -- configuration problem
        log.critical("OAuth client credentials rejected: %s", e)
        raise
    else:
        # Other OAuth errors (invalid_scope, server_error, etc.)
        log.error("OAuth error during token refresh: %s", e)
        raise
except requests.exceptions.ConnectionError:
    # Network failure -- the refresh token is still valid,
    # so retrying is safe
    log.warning("Network error during token refresh, will retry")
    time.sleep(2)
    response = session.get("https://api.example.com/v1/data")

The key distinction is between permanent failures and transient failures. An invalid_grant error means the token is gone and retrying is pointless. A network timeout or a server_error response means the refresh token itself may still be valid and a retry (with backoff) is appropriate. Building this distinction into your error handling prevents both unnecessary re-authentication prompts and infinite retry loops.

Concurrent Refresh and Race Conditions

When multiple threads, processes, or server instances share the same OAuth token, a race condition can occur during refresh. If the authorization server uses token rotation (as recommended by RFC 9700), the first process to refresh the token invalidates the old refresh token. Any other process that attempts to refresh with that same now-invalid token receives an invalid_grant error -- and with reuse detection enabled, the server may revoke the entire token family, locking out all processes until the user re-authenticates.

This is not a theoretical concern. It surfaces regularly in production environments where load-balanced web servers, background workers, or multiple CLI sessions share a single set of credentials. The pattern looks like this: Process A and Process B both detect an expired access token at roughly the same time. Process A refreshes first, gets a new token pair, and invalidates the old refresh token. Process B then sends the old (now dead) refresh token, which triggers reuse detection and revokes everything.

copyimport threading
from authlib.integrations.requests_client import OAuth2Session

# A lock that coordinates refresh across threads
_refresh_lock = threading.Lock()
_shared_token = None

def get_session():
    """Create a session with coordinated token refresh."""

    def coordinated_update(token, refresh_token=None,
                           access_token=None):
        global _shared_token
        _shared_token = token
        save_token_to_database(token, refresh_token=refresh_token,
                               access_token=access_token)

    session = OAuth2Session(
        "your-client-id",
        "your-client-secret",
        token_endpoint="https://auth.example.com/oauth/token",
        update_token=coordinated_update,
    )
    return session

def safe_request(method, url, **kwargs):
    """Make an API request with coordinated refresh.

    Uses a lock to ensure only one thread refreshes at a time.
    Other threads re-read the stored token after the lock releases.
    """
    global _shared_token

    with _refresh_lock:
        session = get_session()
        # Re-read token from storage -- another thread may have
        # already refreshed it while we waited for the lock
        _shared_token = load_token_from_database()
        session.token = _shared_token

        response = session.request(method, url, **kwargs)

    return response

For multi-process deployments (Gunicorn workers, Celery tasks, separate microservices), a thread lock is not sufficient because the lock only works within a single process. In these cases, use a distributed lock backed by Redis, a database advisory lock, or a dedicated token management service that centralizes refresh operations. The core principle is the same: serialize refresh operations so that only one process refreshes at a time, and every other process re-reads the stored token after the refresh completes.

Token Revocation (RFC 7009)

Token refresh keeps sessions alive, but the other side of lifecycle management is ending them cleanly. RFC 7009 defines a standard token revocation endpoint that allows clients to notify the authorization server that a token is no longer needed. When you revoke a refresh token, the server invalidates both the refresh token and any access tokens issued from the same authorization grant. This is the mechanism behind "log out" functionality, account deactivation flows, and credential rotation procedures.

Authlib does not provide a built-in client-side revoke_token() convenience method on OAuth2Session, but the revocation call is a straightforward POST request. The revocation endpoint accepts a token parameter and an optional token_type_hint ("refresh_token" or "access_token") to tell the server which type of token is being revoked.

copyfrom authlib.integrations.requests_client import OAuth2Session

session = OAuth2Session(
    "your-client-id",
    "your-client-secret",
)

def revoke_token(session, revocation_url, token_value,
                 token_type_hint="refresh_token"):
    """Revoke a token per RFC 7009.

    Args:
        session: An authenticated OAuth2Session.
        revocation_url: The provider's revocation endpoint URL.
        token_value: The token string to revoke.
        token_type_hint: "refresh_token" or "access_token".
    """
    response = session.post(
        revocation_url,
        data={
            "token": token_value,
            "token_type_hint": token_type_hint,
        },
    )

    # RFC 7009 requires 200 even for invalid tokens
    # (the goal -- invalidation -- is already achieved)
    if response.status_code == 200:
        # Clean up local storage
        clear_stored_token(user_id=current_user.id)
    else:
        log.warning("Revocation returned %s: %s",
                     response.status_code, response.text)

# On user logout:
revoke_token(
    session,
    "https://auth.example.com/oauth/revoke",
    token_value=current_token["refresh_token"],
    token_type_hint="refresh_token",
)

Not every authorization server supports RFC 7009 -- check your provider's documentation for the revocation endpoint URL. Providers like Auth0, Okta, and Google all support it. If the provider does not offer a revocation endpoint, you cannot force server-side invalidation -- you can only delete the token from your local storage and wait for it to expire naturally.

Using AsyncOAuth2Client with HTTPX

For async applications (FastAPI, Starlette, or any asyncio-based code), Authlib provides AsyncOAuth2Client built on HTTPX. As the Authlib HTTPX documentation confirms, it shares the same token management API as the synchronous OAuth2Session, including automatic refresh and the update_token callback. The callback can be either sync or async.

copyfrom authlib.integrations.httpx_client import AsyncOAuth2Client

async def update_token(token, refresh_token=None, access_token=None):
    """Async callback for token persistence.

    Same signature as the sync version -- Authlib accepts both.
    """
    if refresh_token:
        item = await OAuth2Token.find(
            name=name, refresh_token=refresh_token
        )
    elif access_token:
        item = await OAuth2Token.find(
            name=name, access_token=access_token
        )
    else:
        return

    item.access_token = token["access_token"]
    item.refresh_token = token.get("refresh_token")
    item.expires_at = token["expires_at"]
    await item.save()

client = AsyncOAuth2Client(
    "your-client-id",
    "your-client-secret",
    token_endpoint="https://auth.example.com/oauth/token",
    update_token=update_token,
)

# Load existing token
client.token = await db.get_latest_token()

# Make async API calls with transparent refresh
async with client as c:
    response = await c.get("https://api.example.com/v1/data")
    print(response.json())

Authlib vs requests-oauthlib for Refresh

Both Authlib and requests-oauthlib support token refresh, but they handle it differently. Here is a practical comparison based on each library's official documentation:

Authlib's key advantages for token refresh are the old-token context in the update callback (which enables both database record lookup and rotation detection), the configurable leeway for proactive refresh before expiry, and native async support. If your project already uses requests-oauthlib and works well, there is no urgent need to migrate. For new projects, Authlib provides a more complete and actively maintained foundation for the full OAuth 2.0 token lifecycle.

Key Takeaways

1. Upgrade to Authlib 1.6.9+ immediately: Versions prior to 1.6.9 contain CVE-2026-27962 (CVSS 9.1), a critical JWT forgery vulnerability that allows unauthenticated authentication bypass. Run pip install --upgrade authlib and verify with python -c "import authlib; print(authlib.__version__)".
2. Use Authlib's token_endpoint for automatic refresh: When set, Authlib transparently refreshes tokens before they expire. The default 60-second leeway prevents clock-skew issues. Your application code makes API calls without any awareness of token lifecycle.
3. Use the correct update_token signature: The callback is update_token(token, refresh_token=None, access_token=None) -- not update_token(token, old_token=None). The keyword args provide the old token's string values for database record lookup, not the entire old token dict.
4. Handle token rotation per RFC 6819 and RFC 9700: When the server rotates refresh tokens, always store the new value immediately. Compare the refresh_token keyword argument (old value) with token["refresh_token"] (new value) to detect rotation. Reuse detection by the authorization server can revoke the entire token chain.
5. Distinguish permanent from transient refresh failures: An invalid_grant error means the refresh token is dead and re-authentication is required. Network timeouts and server_error responses are transient and can be retried with backoff. Build both paths into your error handling.
6. Serialize refresh operations in concurrent environments: When multiple threads, processes, or server instances share a token, use a lock (thread lock for single-process, distributed lock for multi-process) to ensure only one refresh happens at a time. Without coordination, token rotation causes race conditions that can revoke the entire token family.
7. Revoke tokens on logout and disconnection (RFC 7009): Deleting a token from your database is not revocation. Call the provider's revocation endpoint to ensure the token is rejected server-side. This is especially important for security events like password changes and integration disconnections.
8. Store tokens securely and treat refresh tokens like passwords: Use encrypted database columns or a secrets manager in production. For local development, use a file with restricted permissions (chmod 0o600) and add it to .gitignore.
9. Choose Authlib for new projects needing refresh: Its built-in auto-refresh, old-token context in the callback, configurable leeway, and native async support make it the more complete choice for token lifecycle management compared to requests-oauthlib.

Token refresh is the mechanism that turns short-lived security tokens into a seamless user experience. Authlib abstracts the protocol-level details so you can focus on what the tokens unlock rather than how they are renewed. Set the token_endpoint, implement the update_token callback with the correct signature, coordinate refresh across concurrent processes, handle failure cases with the right distinction between permanent and transient errors, and revoke tokens cleanly when sessions end. With those pieces in place, your application has a token lifecycle that handles expiration, rotation, persistence, error recovery, and teardown without a single manual refresh call in your business logic.

Sources and Further Reading

• Authlib Documentation: OAuth 2 Session -- official guide to automatic and manual token refresh
• Authlib Client API References -- OAuth2Session constructor parameters including update_token, leeway, and token_endpoint
• Authlib: OAuth for HTTPX -- AsyncOAuth2Client documentation with async update_token examples
• Authlib: Web OAuth Clients -- framework integration patterns for Flask and Django
• Authlib on PyPI -- version history and release notes (v1.6.9, March 2, 2026)
• RFC 6749, Section 1.5 -- The OAuth 2.0 Authorization Framework: Refresh Tokens
• RFC 6819, Section 5.2.2.3 -- OAuth 2.0 Threat Model: Refresh Token Rotation
• RFC 9700 -- Best Current Practice for OAuth 2.0 Security (January 2025)
• RFC 7009 -- OAuth 2.0 Token Revocation: endpoint specification for revoking access and refresh tokens
• Auth0: Refresh Token Rotation -- reuse detection, token family revocation, and grace periods for concurrent requests
• requests-oauthlib API Documentation -- OAuth2Session constructor and token_updater parameter