OAUTH2Relay Get in touch

OAuth2 token relay

Secure OAuth2 tokens,
never on disk.

Secure OAuth2 token management without hard-coded credentials. Tokens live only in memory; credentials come from your environment.

Read the guide See how it works

What is OAUTH2Relay?

Lightweight middleware.
Zero token storage.

OAUTH2Relay is a secure, lightweight middleware designed to simplify OAuth2 token management for third-party API integrations. Unlike traditional solutions, it never stores tokens on disk or in databases—tokens reside exclusively in memory and are wiped at process termination. Credentials (username/password) are sourced securely from environment variables or secrets managers, ensuring no sensitive data is hard-coded in configuration files.

Zero Persistent Token Storage

Tokens live only in volatile memory, erased on process shutdown.

Environment-Driven Credentials

Configuration values (username, password, auth strings) can reference environment variables for airtight security.

Automatic Token Refresh

Seamlessly renews access tokens using refresh tokens, falling back to re-authentication when needed.

Compliance-Ready

Eliminates risks of credential leakage in config files or logs.

Ideal for developers and enterprises prioritizing security, compliance, and simplicity in API integrations (e.g., finance, healthcare, or cloud-native apps).

Advantages

Built for security.
Simple to run.

Military-Grade Security

  • No Hard-Coded Credentials: Username, password, and auth strings are injected via environment variables or secrets managers (e.g., AWS Secrets Manager, HashiCorp Vault).
  • Tokens Never Touch Disk: In-memory storage ensures tokens vanish on process termination or crashes.
  • Audit-Friendly: No credentials or tokens persist in configs, databases, or logs.

DevOps & Cloud-Native Ready

  • Integrates seamlessly with containerized environments (Docker, Kubernetes) and CI/CD pipelines.
  • Supports dynamic credential injection for ephemeral workloads (e.g., serverless functions).

Effortless Compliance

  • Aligns with GDPR, HIPAA, and PCI-DSS by avoiding credential/token persistence.
  • Reduces audit scope—no databases or config files to scrutinize.

Simplified Operations

  • No database setup, token cleanup, or key rotation overhead.
  • Configuration files are static and environment-agnostic.

Resilient by Design

  • Retries token refreshes during third-party API outages.
  • Self-healing: Restarts gracefully re-authenticate using environment-injected credentials.

How does it work?

Four steps.
No secrets left behind.

Your App OAUTH2Relay (In-Memory Tokens + Env Vars) Third-Party API

Step 1 of 4

Secure Credential Injection

Configure user, password, and authstring in your config file to reference environment variables (e.g., $API_USER).

Step 2 of 4

Startup & Authentication

On launch, OAUTH2Relay fetches credentials from environment variables and authenticates with the third-party API. Initial tokens (access + refresh) are stored in memory.

Step 3 of 4

Token Lifecycle Management

For each API request, a valid access token is injected automatically. If expired, the in-memory refresh token is used to obtain a new access token or re-authenticate if necessary.

Step 4 of 4

Shutdown/Crash Safety

All tokens are purged from memory instantly, ensuring no credential traces remain after process termination or crashes.

Security best practices

Harden the
environment too.

  • Use secrets managers (e.g., AWS Secrets Manager, Azure Key Vault) to populate environment variables.
  • Restrict IAM/role permissions to the OAUTH2Relay process.
  • Encrypt environment variables in production (e.g., via Kubernetes Secrets).

Use cases

Wherever an API
needs a token.

From serverless functions to edge devices, OAUTH2Relay keeps credentials out of code and tokens out of storage.

Cloud-Native Applications

Securely integrate with APIs in Kubernetes, AWS Lambda, or Azure Functions, using cloud-native secrets management.

CI/CD Pipelines

Safely authenticate with APIs during deployments (e.g., Terraform, GitHub Actions) without exposing credentials in scripts.

Financial Transactions

Process payments via Stripe or PayPal without risking credential leaks, even in high-availability environments.

Healthcare Data Sync

Connect to HIPAA-compliant EHR systems (e.g., Epic) with credentials sourced from audited secrets managers.

Microservices Architectures

Securely allow stateless services to access third-party APIs, with tokens scoped to each service's lifecycle.

Edge/IoT Devices

Manage API tokens for devices with limited storage—credentials are injected at runtime, and tokens vanish on reboot.

Technical highlights

Configure with
environment variables.

Reference variables like ${ENV_API_USER} in the config file and OAUTH2Relay resolves them at startup, so the file itself never holds a secret.

  • Environment Variable Support: export credentials, then start the relay.
  • Secrets Manager Integration: Works with AWS Secrets Manager, HashiCorp Vault, and more.
  • Flexible Routing: Relay to a single endpoint, pass the request path through, or let callers choose from an allow-listed set of hosts. See relay modes.
terminal
# Example: Launching OAUTH2Relay with environment variables
export ENV_API_USER="client_123"
export ENV_API_PASSWORD="s3cr3t!"

$ cat oauth2relay.json
{
  "port": 8080,
  "host": "0.0.0.0",
  "debug": true,
  "logfile": "oauth2relay.log",
  "login": {
          "user": "${ENV_API_USER}",
          "password": "${ENV_API_PASSWORD}",
          ...
  },
...
}

./oauth2relay start --config oauth2relay.json

FAQ

Questions,
answered.

Use Kubernetes Secrets, AWS Parameter Store, or similar tools to inject variables securely.

Tokens are lost, but OAUTH2Relay auto-reauthenticates on restart using environment variables.

Yes! It's ideal for short-lived functions—tokens exist only during execution.

Yes. In passthrough mode, the request path is appended to a base URL, so one relay covers a whole API. In parameter mode, callers pass the full target URL in a parameter, and it must point to a host in your allowed_hosts list. See Relay Modes.

Contact us

Talk to
the team.

If you have questions or need further assistance, please fill out the form below.

User guide

Configure it
in one file.

This guide provides detailed configuration information for OAUTH2Relay using a sample config.json file.

Example Configuration

config.json
{
  "port": 8080,
  "host": "0.0.0.0",
  "debug": true,
  "logfile": "oauth2relay.log",
  "login": {
    "user": "YOUR_USERNAME",
    "password": "YOUR_PASSWORD",
    "authstring": "${YOUR_AUTHSTRING}",
    "refreshtoken": "",
    "method": "GET",
    "data": "",
    "url": "https://saas.example.com/login",
    "headers": {
      "Authorization": "Basic ${AUTHSTRING}"
    },
    "parameters": {
      "AccessToken": "AccessToken",
      "ExpiresIn": "ExpiresIn",
      "ExpiresAt": "ExpiresAt",
      "TokenType": "TokenType",
      "RefreshToken": "RefreshToken"
    }
  },
  "refresh": {
    "token": "",
    "method": "POST",
    "data": "{\"token\": \"${REFRESHTOKEN}\"}",
    "url": "https://saas.example.com/refresh",
    "headers": {
      "Authorization": "${REFRESHTOKEN}"
    },
    "parameters": {
      "AccessToken": "AccessToken",
      "ExpiresIn": "ExpiresIn",
      "ExpiresAt": "ExpiresAt",
      "TokenType": "TokenType",
      "RefreshToken": "RefreshToken"
    }
  },
  "relay": {
    "mode": "passthrough",
    "url": "https://saas.example.com/",
    "method": "GET",
    "type": "json",
    "fixedtoken": "",
    "data": "",
    "parameters": {
      "country_code": "US"
    },
    "headers": {
      "Authorization": "Bearer ${ACCESSTOKEN}",
      "Content-Type": "application/json"
    }
  }
}

Server Configuration

These parameters configure the middleware server:

  • host: The IP address or hostname (e.g., "0.0.0.0" for all interfaces).
  • port: The TCP port (e.g., 8080).
  • debug: Boolean flag for detailed logging (true or false).
  • logfile: File path for log messages (e.g., "oauth2relay.log").

Login

This section configures the authentication flow to obtain initial tokens:

  • user: The client/user identifier.
  • password: The client's password.
  • authstring: A base64 encoded string (from user:password).
  • refreshtoken: Populated upon authentication success.
  • method: HTTP method (e.g., "GET").
  • url: Endpoint for the login process.
  • headers: Additional HTTP headers used during login.
  • parameters: Mapping of response fields (e.g., AccessToken, ExpiresIn, etc.).

Refresh

This section explains how to obtain a new access token when needed:

  • token: Current refresh token storage (initially empty).
  • method: HTTP method for token refresh (e.g., "POST").
  • data: JSON payload containing a placeholder for the refresh token (${REFRESHTOKEN}).
  • url: Endpoint for refreshing tokens.
  • headers: Additional headers for the refresh call.
  • parameters: Mapping for response fields (e.g., AccessToken, ExpiresIn, etc.).

Relay

This section configures how the middleware relays API requests once a valid token is available:

  • mode: How the target URL is chosen: "single", "passthrough" (default) or "parameter". Case-insensitive. See Relay Modes.
  • url: The target API endpoint for relayed requests. Required in single and passthrough modes.
  • url_param: parameter mode only. The incoming parameter that carries the target URL (default "external_url").
  • allowed_hosts: parameter mode only, and required there. The hosts the target URL may point to, e.g. ["api.example.com", "*.example.com"].
  • method: HTTP method for relay (e.g., "GET").
  • type: Request payload type (e.g., "json").
  • fixedtoken: Optional fixed token parameter (left empty for dynamic management).
  • data: Additional data payload if needed.
  • parameters: Fixed key-value pairs for the relay process.
  • headers: HTTP headers for the relay call, including dynamic insertion of the access token.

Relay Modes

The mode setting decides where each incoming request is sent. Mode names are case-insensitive. If the mode is not recognised, or a setting it needs is missing, OAUTH2Relay refuses to start and reports the problem.

single

Every request goes to one fixed endpoint. The incoming path is ignored.

In
localhost:8000/my_profile
Out
example.com/api/get_statuses

passthrough default

The incoming path is appended to the configured url.

In
localhost:8000/my_profile
Out
example.com/api/my_profile

parameter

The caller names the target URL. The parameter is stripped before relaying.

In
localhost:8000/?external_url=https://example.com/my_profile
Out
example.com/my_profile

In every mode, query parameters, body parameters and the configured parameters are merged into the outbound request in the same way.

single
"relay": {
  "mode": "single",
  "url": "https://example.com/api/get_statuses",
  "method": "GET"
}
passthrough
"relay": {
  "mode": "passthrough",
  "url": "https://example.com/api",
  "method": "GET"
}
parameter
"relay": {
  "mode": "parameter",
  "url_param": "external_url",
  "allowed_hosts": ["example.com", "*.example.com"],
  "method": "GET"
}

In parameter mode, the target URL can arrive in the query string, a form-encoded body or a JSON body. It is removed from all of them, so the 3rd party never sees it. The incoming path is never appended to the target URL. If the 3rd-party API uses its own external_url parameter, choose a different name with url_param.

  • 400 Bad Request: The parameter is missing or is not an absolute http/https URL.
  • 403 Forbidden: The URL's host is not in allowed_hosts. *.example.com matches subdomains only, and an entry with a port matches that port only.

Security: in parameter mode, the access token goes to whichever URL the caller supplies. That is why allowed_hosts is required. Keep it as narrow as possible, and set apiKey so that only trusted services can call the relay.

Keep tokens out of storage.
Start in minutes.

Read the guide Get in touch