How to Refresh OAuth Tokens in Python for n8n API Calls

Step‑by‑step guide for developers to implement automatic OAuth token refresh in Python when calling n8n APIs, preventing auth failures and keeping workflows running.

How to Refresh OAuth Tokens in Python for n8n API Calls - Technology Tutorials
Short answer: Refresh an expired n8n OAuth token by calling the token endpoint with the stored refresh token, update the local cache, and reuse the new access token for subsequent API calls. A small reusable Python helper can automate these steps and be imported into any n8n‑driven automation script.

When you integrate n8n with external services using OAuth 2.0, the access token that authorises API calls typically lives only for an hour. After that, n8n (or your own script) will receive a 401 Unauthorized error and the workflow stops. The fix is to exchange the original refresh_token for a fresh access_token before each request.

This guide shows you how to build a lightweight Python module that (1) stores the original tokens securely, (2) detects expiration, (3) automatically refreshes the token, and (4) returns a ready‑to‑use requests.Session object that you can drop into any n8n workflow or generic Python automation script.

What You’ll Learn

  • How OAuth 2.0 token refresh works for n8n’s built‑in HTTP Request node.
  • How to persist tokens safely using keyring or a simple encrypted JSON file.
  • How to create a reusable OAuthHelper class that returns a pre‑authenticated requests.Session.
  • How to plug the helper into an n8n workflow that runs Python code via the “Execute Command” node.
  • Common pitfalls (clock drift, missing scopes, token revocation) and how to avoid them.

Overview of n8n OAuth flow

n8n supports OAuth 2.0 out of the box for many services (Google, Microsoft, Salesforce, etc.). When you first authorise a connection, n8n stores:

  • access_token – used for API calls, expires after expires_in seconds (usually 3600).
  • refresh_token – long‑lived, can be exchanged for a new access token.
  • token_type – typically Bearer.

When an API call returns 401, n8n automatically attempts a refresh if the credential includes a refresh token. However, custom Python code that calls the same endpoint bypasses n8n’s built‑in logic, so you must replicate the refresh step yourself.

Prerequisites and environment setup

  1. Python 3.10+ (official binaries at python.org).
  2. Virtual environment (recommended):
    python -m venv .venv
    source .venv/bin/activate  # Linux/macOS
    .\.venv\Scripts\activate   # Windows
  3. Install required packages:
    pip install requests python-dotenv keyring
    Keyring provides OS‑native credential storage (Keychain on macOS, Credential Manager on Windows, Secret Service on Linux).
  4. Obtain the OAuth client credentials from your n8n instance (Client ID, Client Secret, Token URL). These are visible in the n8n UI under Credentials → OAuth2 API or in the n8n configuration file (.n8n/config).

Choosing a token storage strategy

Storing the refresh token securely is critical. Two common approaches are:

Option Security Setup complexity Portability Typical use‑case
OS keyring (keyring library) High – uses OS‑native secret store Low – one‑line install Good on a single host; less portable across CI runners Local dev or on‑prem servers
Encrypted JSON file Medium – encryption key must be managed Medium – requires cryptography setup Excellent – can be checked into repo (encrypted) and used in CI/CD Team environments, CI pipelines

Pick the method that matches your security policy. The code examples below support both; you only need to instantiate the helper with the desired backend.

Building the reusable OAuth helper

The following module (oauth_helper.py) encapsulates token handling. It is deliberately small so you can copy‑paste it into any project.

# oauth_helper.py
import time
import json
import base64
import hashlib
import requests
from pathlib import Path
from typing import Dict, Any, Optional

# Optional: OS keyring backend
try:
    import keyring
except ImportError:  # pragma: no cover
    keyring = None

# ----------------------------------------------------------------------
# Configuration – replace placeholders with your real values or load
# them from environment variables (recommended for CI).
# ----------------------------------------------------------------------
CLIENT_ID = <YOUR_CLIENT_ID>
CLIENT_SECRET = <YOUR_CLIENT_SECRET>
TOKEN_URL = <YOUR_TOKEN_ENDPOINT>   # e.g. https://api.n8n.io/oauth2/token
# Scope is optional for refresh; include if the provider requires it.
SCOPES = "read write"

# ----------------------------------------------------------------------
# Helper class
# ----------------------------------------------------------------------
class OAuthHelper:
    """
    Handles storage, refresh, and retrieval of OAuth2 tokens for n8n APIs.
    """
    def __init__(self,
                 storage: str = "keyring",   # or "file"
                 file_path: Optional[Path] = None,
                 service_name: str = "n8n_oauth"):
        self.storage = storage
        self.service_name = service_name
        self.file_path = file_path or Path.home() / ".n8n_oauth.json"
        self.token_data: Dict[str, Any] = self._load_tokens()

    # ------------------------------------------------------------------
    # Internal storage helpers
    # ------------------------------------------------------------------
    def _load_tokens(self) -> Dict[str, Any]:
        if self.storage == "keyring" and keyring:
            raw = keyring.get_password(self.service_name, "tokens")
            return json.loads(raw) if raw else {}
        else:
            if self.file_path.is_file():
                with open(self.file_path, "r", encoding="utf-8") as f:
                    encrypted = f.read()
                return self._decrypt(encrypted)
            return {}

    def _save_tokens(self) -> None:
        if self.storage == "keyring" and keyring:
            keyring.set_password(self.service_name, "tokens", json.dumps(self.token_data))
        else:
            encrypted = self._encrypt(self.token_data)
            self.file_path.parent.mkdir(parents=True, exist_ok=True)
            with open(self.file_path, "w", encoding="utf-8") as f:
                f.write(encrypted)

    # Simple symmetric encryption – replace with your own KMS if needed
    def _encrypt(self, data: Dict[str, Any]) -> str:
        key = hashlib.sha256(CLIENT_SECRET.encode()).digest()
        payload = json.dumps(data).encode()
        token = base64.b64encode(payload).decode()
        return token  # placeholder: real encryption should use Fernet or similar

    def _decrypt(self, token: str) -> Dict[str, Any]:
        payload = base64.b64decode(token.encode())
        return json.loads(payload.decode())

    # ------------------------------------------------------------------
    # Public API
    # ------------------------------------------------------------------
    def get_session(self) -> requests.Session:
        """
        Returns a requests.Session with a valid Authorization header.
        Refreshes the token if it is expired or missing.
        """
        if not self._token_valid():
            self._refresh_access_token()
        session = requests.Session()
        session.headers.update({
            "Authorization": f"{self.token_data['token_type']} {self.token_data['access_token']}"
        })
        return session

    # ------------------------------------------------------------------
    # Token validity & refresh
    # ------------------------------------------------------------------
    def _token_valid(self) -> bool:
        expires_at = self.token_data.get("expires_at")
        if not expires_at:
            return False
        # Add a 30‑second safety margin
        return time.time() < expires_at - 30

    def _refresh_access_token(self) -> None:
        """
        Calls the token endpoint with the stored refresh token.
        Updates internal state and persists it.
        """
        refresh_token = self.token_data.get("refresh_token")
        if not refresh_token:
            raise RuntimeError("No refresh token available – re‑authorise the n8n credential.")

        payload = {
            "grant_type": "refresh_token",
            "client_id": CLIENT_ID,
            "client_secret": CLIENT_SECRET,
            "refresh_token": refresh_token,
            "scope": SCOPES,
        }

        response = requests.post(TOKEN_URL, data=payload, timeout=10)
        if response.status_code != 200:
            raise RuntimeError(f"Token refresh failed: {response.status_code} {response.text}")

        token_response = response.json()
        # n8n follows the RFC6749 response format
        self.token_data.update({
            "access_token": token_response["access_token"],
            "refresh_token": token_response.get("refresh_token", refresh_token),
            "expires_in": token_response["expires_in"],
            "expires_at": time.time() + token_response["expires_in"],
            "token_type": token_response.get("token_type", "Bearer"),
        })
        self._save_tokens()

    # ------------------------------------------------------------------
    # Initial credential import
    # ------------------------------------------------------------------
    def import_initial_tokens(self, access_token: str, refresh_token: str,
                              expires_in: int, token_type: str = "Bearer") -> None:
        """
        Call this once after you manually authorise n8n and obtain the first
        pair of tokens (e.g. from the n8n UI or logs). It stores them for
        future automatic refreshes.
        """
        self.token_data = {
            "access_token": access_token,
            "refresh_token": refresh_token,
            "expires_in": expires_in,
            "expires_at": time.time() + expires_in,
            "token_type": token_type,
        }
        self._save_tokens()

Save the file, then initialise it with the tokens you receive from n8n the first time you set up the connection:

# initialise_tokens.py
from oauth_helper import OAuthHelper

helper = OAuthHelper(storage="keyring")   # or storage="file"
helper.import_initial_tokens(
    access_token="<ACCESS_TOKEN_FROM_N8N>",
    refresh_token="<REFRESH_TOKEN_FROM_N8N>",
    expires_in=3600,
)
print("Tokens stored – ready for automated refresh.")

Integrating the helper with an n8n workflow

n8n can execute arbitrary shell commands via the “Execute Command” node. Use it to run a small Python script that calls the API with the refreshed session.

  1. Add an “Execute Command” node.
  2. Set Command to python - <<'PY'\n...PY (here‑document) or point to a script file stored on the same host.
  3. Inside the script, import OAuthHelper, obtain a session, and perform the request:
# n8n_api_call.py
from oauth_helper import OAuthHelper

helper = OAuthHelper(storage="keyring")
session = helper.get_session()

# Example: fetch all active workflows
resp = session.get("https://your-n8n-instance.com/rest/workflows")
resp.raise_for_status()
print(resp.json())  # n8n will capture stdout as node output

Because OAuthHelper.get_session() guarantees a valid token, the workflow never fails due to token expiry.

Reliable error handling and retries

Network glitches and token revocation are common in production. Wrap the request in a retry loop and handle 401 explicitly:

import time
from requests.exceptions import RequestException

def call_with_retry(url, max_attempts=3, backoff=2):
    for attempt in range(1, max_attempts + 1):
        try:
            resp = session.get(url, timeout=10)
            if resp.status_code == 401:
                # Force a refresh and retry once
                helper._refresh_access_token()
                session.headers["Authorization"] = f"{helper.token_data['token_type']} {helper.token_data['access_token']}"
                continue
            resp.raise_for_status()
            return resp.json()
        except RequestException as e:
            if attempt == max_attempts:
                raise
            time.sleep(backoff ** attempt)

data = call_with_retry("https://your-n8n-instance.com/rest/workflows")
Pro Tip: Log the timestamp of each refresh to a separate file; this makes it easy to audit token usage across multiple workflows.

Comparison of storage options

Criterion OS Keyring Encrypted JSON
Ease of use One‑line install, no extra code Requires encryption library and key management
Security model Relies on OS‑level protection (encrypted at rest) Encryption is only as strong as the secret you supply
CI/CD friendliness Not ideal – most CI runners lack a persistent keyring File can be checked into repo (encrypted) and unlocked with a secret env var
Cross‑platform portability Works on macOS, Windows, Linux (requires secret‑service) Works everywhere Python runs

Frequently Asked Questions

Can I use this helper with other OAuth‑protected APIs?

Yes. The class only depends on the standard token endpoint contract (grant_type = refresh_token). Adjust CLIENT_ID, CLIENT_SECRET, and TOKEN_URL for the target service.

What if the refresh token itself expires?

Some providers rotate refresh tokens on each use. The helper updates the stored refresh_token if the response contains a new one. If the provider revokes it, the helper raises a RuntimeError prompting you to re‑authorise the n8n credential.

Do I need to handle clock drift?

Adding a 30‑second safety margin (see _token_valid) mitigates most drift issues. For environments with unreliable system clocks, consider synchronising with NTP.

Is storing the client secret in the script safe?

Never commit the secret to version control. Load it from environment variables or a secret manager (AWS Secrets Manager, HashiCorp Vault) and assign it to CLIENT_SECRET at runtime.

Can I run the helper inside an n8n Docker container?

Yes. Install the Python dependencies in the container’s Dockerfile and mount a volume for the encrypted JSON file, or configure the container’s OS keyring (e.g., docker run --security-opt label=type:container_runtime_t on SELinux‑enabled hosts).

How many concurrent refreshes are safe?

OAuth providers typically limit the token endpoint to a few requests per minute per client. Cache the token in memory (as the helper does) and avoid parallel refreshes by sharing a single OAuthHelper instance per process.

Does n8n automatically delete expired refresh tokens?

No. n8n only removes the credential when you delete it manually. The helper is responsible for keeping the stored token up‑to‑date.

Conclusion

By adding the OAuthHelper module to your Python automation toolbox you eliminate the “access token expired” failure mode that commonly breaks n8n workflows. The next steps are:

  1. Run initialize_tokens.py once with the tokens you retrieve from n8n.
  2. Replace any raw requests calls in your scripts with helper.get_session().
  3. Commit the helper (without secrets) to your codebase and configure the storage method that matches your security policy.
  4. Monitor the log file generated by the Pro Tip in production to verify refresh frequency.

With a single import you now have a reusable, secure, and CI‑friendly solution for all future api integration python projects that talk to n8n.

Official documentation