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
keyringor a simple encrypted JSON file. - How to create a reusable
OAuthHelperclass that returns a pre‑authenticatedrequests.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_inseconds (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
- Python 3.10+ (official binaries at python.org).
- Virtual environment (recommended):
python -m venv .venv source .venv/bin/activate # Linux/macOS .\.venv\Scripts\activate # Windows - Install required packages:
pip install requests python-dotenv keyringKeyring provides OS‑native credential storage (Keychain on macOS, Credential Manager on Windows, Secret Service on Linux).
- 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.
- Add an “Execute Command” node.
- Set Command to
python - <<'PY'\n...PY(here‑document) or point to a script file stored on the same host. - 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:
- Run
initialize_tokens.pyonce with the tokens you retrieve from n8n. - Replace any raw
requestscalls in your scripts withhelper.get_session(). - Commit the helper (without secrets) to your codebase and configure the storage method that matches your security policy.
- 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
- n8n OAuth2 credential documentation
- OAuth 2.0 Authorization Framework (RFC 6749)
- Requests library
- Keyring Python package
- Python json module



