Infisical Proxy

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

How It Works

%%{init: {'theme': 'base', 'themeVariables': { 'edgeLabelBackground':'#ffffff', 'lineColor': '#333'}}}%%
flowchart LR
    A[Application] -->|Request| B[Infisical Proxy]
    B -->|Cache Hit| A
    B -->|Cache Miss| C[Infisical]
    C -->|Response| B
    B -->|Cache & Return| A
    
    style A fill:#ECF26D,stroke:#333,color:#000
    style B fill:#ECF26D,stroke:#333,color:#000
    style C fill:#ECF26D,stroke:#333,color:#000

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.

To enable event subscriptions with a minimal configuration, you need to provide the client ID and client secret for the machine identity used to authenticate the Event Subscription connection to Infisical. You can create a machine identity in the Infisical Dashboard or using the Infisical CLI. Once you have the client ID and client secret, you can start the proxy with the following command:

infisical proxy start \
  --domain=https://app.infisical.com \
  --listen-address=localhost:8081 \
  --tls-enabled=false \
  --enable-event-subscriptions \
  --client-id=<your-client-id> \
  --client-secret=<your-client-secret>

Then configure your application to use http://localhost:8081 as the Infisical host instead of https://app.infisical.com.

For more information on event subscriptions, refer to the Cache refreshing via Event Subscriptions section. </Accordion>

Configuration

Command Options

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. </ParamField>

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. </ParamField>

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.

Cache refreshing via Event Subscriptions

When --enable-event-subscriptions is enabled, the proxy opens a long-lived Event Subscription connection to Infisical's Events API using Sever-sent events (SSE). This allows the proxy to receive real-time notifications when secrets change and immediately re-fetch the affected secrets to update its cache, rather than waiting for the next polling interval.

The proxy subscribes to the following events:

When any of these events are received, the proxy identifies the affected cache entries based on the event's project, environment, and secret path, then re-fetches those entries from Infisical to update the cache with fresh values.

Fallback to Static Secrets Refresh: When the SSE connection is active, the proxy relies on real-time events to keep the cache up to date. If the SSE connection fails, the proxy automatically falls back to the static secrets refresh mechanism, periodically polling Infisical to re-fetch cached secrets based on the --polling-fallback-interval. The proxy will continue attempting to reconnect the SSE connection, and once re-established, polling stops and real-time event-based refresh resumes.

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.

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)

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

<Note>
  The `static-secrets-refresh-interval` is the interval at which the proxy will refresh cached secrets from Infisical.
</Note>

For immediate invalidation, perform mutations through the proxy.