Skip to main content

​
Overview

Infisical Proxy is a client-side daemon that acts as an API proxy for Infisical, providing caching capabilities for high availability. Applications connect to the proxy instead of directly to Infisical, and the proxy handles request forwarding, response caching, and automatic cache refresh. Key features:
  • API Proxy: Forwards all requests to your Infisical instance transparently
  • Caching: Caches secret responses in-memory with automatic refresh
  • High Availability: Continues serving cached secrets even when Infisical is unreachable (optimistic eviction strategy)
  • Automatic Cache Invalidation: Purges stale cache entries when secrets are mutated through the proxy
  • Token Validation: Periodically validates access tokens and evicts entries for revoked tokens
  • TLS Support: Supports TLS encryption for secure communication
The Infisical Proxy is ideal for scenarios where you need to reduce load on your Infisical instance, improve response times, or ensure secret availability during network disruptions.

​
How It Works

The Infisical Proxy sits between your applications and your Infisical instance, acting as a transparent intermediary. Applications make requests to the proxy using the same API endpoints they would use with Infisical directly, simply replace your Infisical host URL with the proxy’s address. The proxy handles authentication headers transparently, forwarding them to Infisical as needed. When a request arrives, the proxy first checks its in-memory cache for a matching response. Cache lookups are based on the request method, path, query parameters, and authentication token, ensuring that different users and query variations are cached separately. If a matching entry exists, the proxy returns the cached response immediately without contacting Infisical, significantly reducing latency and load on your Infisical instance. For requests that aren’t in the cache, the proxy forwards them to Infisical, waits for the response, and then stores the response in its cache before returning it to the application. This means the first request for any unique combination of parameters will have normal latency, but subsequent identical requests will be served from cache. To keep cached data fresh, the proxy runs two background processes. The first periodically validates that cached access tokens are still valid by making test requests to Infisical. If a token has been revoked, all cache entries associated with that token are immediately evicted. The second process refreshes cached secrets on a configurable interval, re-fetching data from Infisical and updating the cache with the latest values. Both processes use an optimistic strategy: if Infisical is unreachable, the proxy continues serving cached data rather than evicting entries, ensuring your applications remain operational during outages.

​
Install the Infisical Proxy

The Infisical Proxy is available through the Infisical CLI. Please refer to the CLI installation documentation for more information on how to install the Infisical CLI.

​
Quick Start

Start the proxy with minimal configuration: 
infisical proxy start \
  --domain=https://app.infisical.com \
  --listen-address=localhost:8081 \
  --tls-enabled=false
Then configure your application to use http://localhost:8081 as the Infisical host instead of https://app.infisical.com.
For production deployments, it is strongly recommended to enable TLS by providing --tls-cert-file and --tls-key-file, and setting --tls-enabled to true.

​
Configuration

​
Command Options

​
--domain
string
required
Domain of your Infisical instance (e.g., https://app.infisical.com)
​
--listen-address
string
required
Address and port for the proxy to listen on, e.g. localhost:8081
​
--tls-enabled
boolean
default:true
Whether to enable TLS encryption for secure communication for the proxy. Defaults to true.Note that all communication between the proxy and Infisical is always encrypted by default. If you are self-hosting your Infisical instance, ensure that your Infisical instance is configured to use TLS.
​
--tls-cert-file
string
Path to the TLS certificate file to use for proxy TLS encryption. This field is required if --tls-enabled is true.
​
--tls-key-file
string
Path to the TLS private key file. This field is required if --tls-enabled is true.
​
--eviction-strategy
string
default:"optimistic"
The eviction strategy to use for cached secrets. Defaults to optimistic, and currently this is the only supported eviction strategy.The eviction strategy is used to determine when to evict cached secrets from the cache.
  • optimistic - Only evict cached secrets when the proxy is able to reach Infisical and verify that the underlying cached secret is stale.
​
--access-token-check-interval
duration
default:"5m"
How often to validate that access tokens are still valid. If a token is deemed to be invalid (such as if it has been revoked or has expired), the proxy will evict all cached secrets that are associated with that token. Supports duration formats like 60s|5m|1h|1d|1w|1y.
​
--static-secrets-refresh-interval
duration
default:"1h"
How often to refresh cached secrets from Infisical. Defaults to 1h. Supports duration formats like 60s|5m|1h|1d|1w|1y.

​
Caching Behavior

​
What Gets Cached

The proxy selectively caches responses to optimize for the most common secret retrieval patterns. Only GET requests to secret endpoints are cached. This includes the list and retrieve endpoints across both API versions (/api/v3/secrets and /api/v4/secrets), as well as their raw variants and any sub-paths. These endpoints represent read operations where caching provides the most benefit: reducing latency for frequently accessed secrets and decreasing load on your Infisical instance. All other requests pass through the proxy without caching. This includes mutation operations like creating, updating, or deleting secrets (POST, PATCH, DELETE), as well as requests to non-secret endpoints such as authentication, project management, or user operations. These requests are forwarded directly to Infisical and their responses are returned to the application without being stored. This design ensures that write operations always reach Infisical immediately and that the cache only contains secret data that benefits from being cached.

​
Request Uniqueness

Each cache entry is uniquely identified by a SHA-256 hash of the request’s method, path, query parameters, and authentication token. This ensures that different query combinations and users are cached separately. The cache key is constructed as follows: 
sha256(method + path + query + access_token)

​
Automatic Cache Refresh

The proxy automatically refreshes cached secrets and validates cached access tokens to ensure the data in the cache remains fresh and valid.

​
Access Token Validation

The proxy periodically validates that cached access tokens are still valid, running every 5 minutes by default. For each unique token in the cache, the proxy makes a test request to Infisical using one of that token’s cached requests. If Infisical returns 401 Unauthorized or 403 Forbidden, all cache entries associated with that token are immediately evicted. When the proxy is configured with the optimistic eviction strategy: If Infisical is unreachable during token validation (network errors or 5xx responses), the proxy keeps cached entries intact rather than evicting them. This ensures that your applications remain operational even if Infisical is temporarily unavailable.

​
Static Secrets Refresh

The proxy automatically refreshes cached secrets to ensure data stays current, running every hour by default. During each refresh cycle, the proxy identifies all cache entries that were last updated longer ago than the refresh interval, then re-fetches each one from Infisical. Successful responses update the cached data with fresh values. Entries that return 401, 403, or 404 during refresh are evicted from the cache, as these indicate the token has lost access or the resource no longer exists. When the proxy is configured with the optimistic eviction strategy: If Infisical is unreachable during the refresh cycle (network errors or 5xx responses), the proxy keeps cached entries intact rather than evicting them. This ensures that your applications remain operational even if Infisical is temporarily unavailable.

​
Mutation-Based Cache Invalidation

When a mutation request is processed through the proxy (POST, PATCH, or DELETE requests), the proxy extracts the projectId, environment, and secretPath from the request body and purges all cache entries that match these criteria—regardless of which token was used to cache them. This cross-token purging ensures that all users see consistent data after a secret is modified. The proxy also supports wildcard path matching, so a mutation to /production/database will invalidate cache entries for both exact path matches and recursive queries that included that path.
For immediate cache invalidation, perform secret mutations through the proxy rather than directly to Infisical. For optimal performance it’s recommended to use the proxy for all API requests.

​
Eviction Strategy

The eviction strategy is used to determine when to evict cached entries from the cache. Currently the Infisical Proxy only supports the optimistic eviction strategy.

​
Optimistic Eviction

  • Keeps cached data when Infisical is unreachable (network errors, or 5xx responses)
  • Ensures high availability when your Infisical instance is unreachable
  • Cache entries are only evicted on:
    • Token invalidation (401/403 response)
    • Resource not found (404 response)
    • Explicit mutation through the proxy
    • Proxy restart (when the proxy is restarted, all cached entries are evicted because the cache is stored in memory)
The optimistic eviction strategy prioritizes availability. Applications will continue receiving cached secrets even if Infisical is down, at the cost of potentially serving slightly stale data.

​
TLS Configuration

By default, TLS is enabled. For production deployments, provide your TLS certificate and key: 
infisical proxy start \
  --domain=https://app.infisical.com \
  --listen-address=0.0.0.0:8081 \
  --tls-cert-file=/path/to/cert.pem \
  --tls-key-file=/path/to/key.pem
To disable TLS (not recommended for production): 
infisical proxy start \
  --domain=https://app.infisical.com \
  --listen-address=localhost:8081 \
  --tls-enabled=false

​
Examples

​
Using the Proxy with SDKs

Configure your Infisical SDK to point to the proxy instead of Infisical directly:

​
Node.js

import { InfisicalSDK } from '@infisical/sdk'

const client = new InfisicalSDK({
  siteUrl: "http://localhost:8081", // Proxy address instead of Infisical
  // ... other configuration options
});

​
Python SDK

from infisical_sdk import InfisicalSDKClient
client = InfisicalSDKClient(host="http://localhost:8081") # Proxy address instead of Infisical

​
Direct API Calls

# Instead of calling Infisical directly:
# curl https://app.infisical.com/api/v3/secrets/raw?...

# Call the proxy:
curl -G http://localhost:8081/api/v4/secrets \
  -H "Authorization: Bearer <your-access-token>" \
  --data-urlencode "projectId=<your-project-id>" \
  --data-urlencode "environment=dev" \
  --data-urlencode "secretPath=/" \
  --data-urlencode "recursive=true"

​
Security Considerations

​
Cache Encryption

All cached secret data is encrypted at rest in memory using AES-256 with GCM authentication. Secrets are only decrypted momentarily when serving a response to a client, and are otherwise stored in encrypted form. The encryption key is randomly generated at proxy startup and persists only for the lifetime of the process, and restarting the proxy generates a new key and clears all cached data. The encryption key itself is protected in memory, using multiple layers of memory protection techniques.
  • Memory locking via mlock(): prevents the key from being swapped to disk
  • Memory protection via mprotect(): guards against buffer overflows and unauthorized access
  • Secure allocation via mmap(): ensures the memory region is allocated safely
  • In-memory encryption using XSalsa20-Poly1305: protects the key even within RAM

​
Network Security

Enable TLS in production to encrypt traffic between your applications and the proxy. Without TLS, secrets are transmitted in plaintext over the network between your applications and the proxy.

​
Access Control

Restrict network access to the proxy’s listen address to prevent unauthorized clients from querying cached secrets. The proxy should only be accessible to trusted applications within your infrastructure.

​
Token Isolation

The proxy caches responses separately for each authentication token. If a token is compromised, only the cache entries associated with that specific token are exposed. Other tokens’ cached data remains isolated and protected.

​
Troubleshooting

If you’re updating secrets directly in Infisical (not through the proxy), the proxy will not automatically invalidate the cache. You will need to manually purge the cache by restarting the proxy, or by waiting for the next static-secrets-refresh-interval cycle.
The static-secrets-refresh-interval is the interval at which the proxy will refresh cached secrets from Infisical.
For immediate invalidation, perform mutations through the proxy.