Secrets Platform Architecture: Infisical, Machine Identities, and Vault Boundaries

API Backend

The REST API is the single entry point for everything. A request arrives, the API validates the bearer token, checks RBAC for the requested operation and path, then either returns the secret value or denies the request. There is no side channel. The audit log entry is written on every request, success or failure.

Infisical Cloud routes all traffic through Cloudflare, which enforces TLS and terminates DDoS traffic. Self-hosted instances must configure TLS at the reverse proxy layer. The API requires TLS 1.2 or higher and does not serve requests over plaintext HTTP.

Storage Backend: PostgreSQL

All secrets, user records, project configs, RBAC policies, and audit events live in Postgres. Secret values are encrypted at the application layer before being written. The database holds ciphertext, not plaintext. An attacker with read access to the Postgres instance sees encrypted blobs without the decryption keys, which live separately in the API server's key store.

For Infisical Cloud, the database is a managed Postgres instance inside the platform's private network. For self-hosting, you provide the Postgres connection string.

Caching and Queue Layer: Redis

Redis serves three roles. It caches frequently-accessed resources (project metadata, RBAC policies) so that common read paths do not hit Postgres on every request. It backs the async task queue for long-running operations like secret rotation jobs and webhook delivery. It also stores scheduled cron job state, including rotation schedules for dynamic secrets.

The caching layer is a correctness concern, not just a performance one. An RBAC policy change must invalidate cached policies. Infisical handles this internally; you should not bypass the API to write directly to the database, because the cache invalidation will not fire.

Clients

Six delivery surfaces exist for applications and users:

• Web UI: Browser portal for managing secrets, configuring identities, reviewing audit logs, and setting up integrations.
• CLI (infisical): Terminal tool for interactive use, scripting, and CI pipelines. infisical run -- <command> spawns a child process with secrets injected as environment variables. Nothing is written to disk.
• SDKs: Runtime libraries for Node.js, Python, Java, Go, Ruby, and .NET. Fetch secrets at startup, inject into process.env, or query individual values by name.
• Kubernetes Operator: A Kubernetes-native CRD controller. Syncs secrets from Infisical into Kubernetes Secrets objects. Applications read from K8s secrets as normal; the operator keeps values current.
• Infisical Agent: A daemon that runs alongside your application. It handles token acquisition, renewal, and secret templating, then writes a rendered config file or populates the environment for the process it manages.
• Secret Syncs: Push integrations that mirror secrets into third-party systems: GitHub Actions secrets, AWS Parameter Store, Vercel environment variables, and more.

Projects

A project is the top-level container for one service or product. Each project has its own set of environments, its own secret namespace, and its own access control list. Machine Identities are assigned to projects and scoped to specific environment+path combinations within them.

Environments

Each project gets three environments by default: dev, staging, and production. You can add custom environments. The same secret name can exist in each environment with a different value. A DATABASE_URL in dev points to a local Postgres; the same key in production points to the managed instance with SSL and a connection pooler.

Folder Paths

Within an environment, secrets are organized into folder paths. The root path / holds shared top-level secrets. Subpaths group by domain: /ai, /database, /payments, /storage. This matters for RBAC. A Machine Identity running the billing service can be scoped to production /payments only. It cannot read the AI keys in production /ai even if it tries. The scoping is enforced at the API layer, not at the application layer.

Universal Auth

The default auth method for servers and CI pipelines. The identity gets a clientId and a clientSecret. These two values are the bootstrap credentials: the only secrets that must exist outside Infisical. Store them in your platform's secret management (Vercel env vars, GitHub Actions secrets). At startup, the application exchanges them for a short-lived Infisical access token and uses that token for all secret fetches.

OIDC Auth

For workloads running on platforms that issue OIDC tokens (GitHub Actions, GitLab CI, AWS EKS, GCP Cloud Run), you can skip the clientSecret entirely. The CI system issues a JWT bound to the workflow run. Infisical verifies the JWT signature against the provider's JWKS endpoint, checks audience and claim conditions you configure, and issues an access token. No static secret is exchanged. The bootstrap problem disappears.

This is the preferred method for GitHub Actions. The workflow requests an OIDC token, Infisical verifies it, and secrets are fetched for that run only. A leaked token is useless after the run ends.

Platform-Native Auth (AWS, GCP, Azure, Kubernetes)

For workloads on major cloud platforms, Infisical can verify platform-issued identity assertions directly. An EC2 instance authenticates using AWS SigV4 against the EC2 metadata service. A GKE pod presents its service account JWT. An AKS deployment uses its managed identity. The platform validates the assertion against its native authentication endpoint and issues an Infisical token. No client secret is managed by the application at all.

Lockout and Rate Limiting

Universal Auth login endpoints have lockout enabled by default. 3 consecutive failed login attempts within a 30-second window locks the endpoint for 5 minutes. This is a brute-force defense for the bootstrap credentials. OIDC and platform-native methods are not affected because they do not use passwords. For Universal Auth in automated systems, use a retry budget with backoff rather than aggressive retry loops, since failures will lock the identity.

CLI Injection: infisical run

The simplest integration. Wrap your start command with infisical run --env=production -- node server.js. Infisical authenticates, fetches all secrets at the configured path, and injects them as environment variables into the child process. The parent shell sees nothing. Nothing is written to disk. The secrets are visible only inside the running process.

SDK: Runtime Fetch

The SDK authenticates at process startup and fetches secrets at runtime. This is the right choice for long-running servers, Vercel functions, and any runtime where you want to handle secret values in code rather than rely on environment variable injection. The key pattern: authenticate once at module scope, cache the SDK client, then fetch secrets by name or inject a whole path into process.env in one call.

Note that getSecret throws a StatusCode=404 error when the secret is absent. This is correct behavior. A missing secret at startup should crash the process loudly, not produce a silent undefined that causes a downstream failure two minutes later.

Kubernetes Operator

The Kubernetes Operator syncs Infisical secrets into Kubernetes Secret objects using CRDs. Applications read from K8s secrets as normal through environment variable references or volume mounts. The operator watches for changes in Infisical and re-syncs on updates. This keeps the interface familiar for teams already using K8s secrets, while making Infisical the single source of truth for values.

The operator authenticates using Kubernetes Auth (the pod's own service account JWT). No static credentials are stored in the cluster. The CRD definition specifies which project, environment, and path to sync, and into which Kubernetes namespace and Secret name to write.

Infisical Agent

The Agent is a sidecar daemon that handles token lifecycle and secret templating for processes that cannot use the SDK or CLI. It authenticates, keeps its token refreshed, and can write rendered configuration files using a template syntax. Applications read a local file or socket rather than calling the Infisical API directly. The Agent abstracts the auth complexity away from the application entirely.

Secret Syncs (Push Integrations)

For platforms that expect secrets in their own native format, Infisical can push values outward. Supported targets include GitHub Actions repository secrets, Vercel project environment variables, AWS Parameter Store, AWS Secrets Manager, GCP Secret Manager, and more. The sync runs when secrets change in Infisical. This means you edit secrets once in Infisical and let the sync push to the downstream platform, rather than maintaining values in two places.

Encryption at Rest

Secret values are encrypted at the application layer before being written to PostgreSQL. The database holds ciphertext. Infisical uses proven symmetric encryption (AES-256) for stored secrets. The encryption keys are managed by the API server, not stored alongside the ciphertext in the database.

This design means that read access to the PostgreSQL instance does not expose secret values. An attacker who dumps the database gets encrypted blobs. They need the application-layer keys to decrypt them, and those keys are not in the database.

Encryption in Transit

All client-to-server communication goes over TLS. Infisical Cloud routes through Cloudflare, which enforces TLS 1.2 as a minimum and provides DDoS protection. For self-hosted instances, TLS termination is the operator's responsibility (typically at an nginx or Caddy reverse proxy in front of the Infisical containers).

Audit Log

Every operation generates an audit event. Reads, writes, role changes, auth failures, and policy updates all appear in the audit log with a timestamp, actor identity, source IP, user agent, and relevant metadata. The log is append-only. You cannot delete entries through the API. For compliance requirements (SOC 2, ISO 27001), the audit log is the primary evidence trail for secret access patterns.

What the Threat Model Covers

• Eavesdropping on communications: TLS on all client-server and server-storage paths.
• Data tampering: Integrity checks at the storage layer; inconsistencies abort transactions and raise alerts.
• Unauthorized access: Every inbound request requires a valid bearer token with sufficient RBAC permissions for the requested operation and path.
• Actions without accountability: Audit log covers all mutations and sensitive reads.
• Storage confidentiality breach: Application-layer encryption means plaintext never touches the database.
• Anomalous access patterns: Infisical monitors for authentication attempts from previously unseen sources.

What the Threat Model Does Not Cover

• Uncontrolled database access: An attacker with full PostgreSQL write access can manipulate or delete data in ways the application cannot prevent.
• Runtime memory intrusion: A process with access to the live Infisical server's memory can extract decrypted values in flight.
• Compromised client identities: If a machine identity's credentials are exposed, the attacker has access at that identity's permission level.
• Administrator configuration tampering: Admin access to the Infisical dashboard can change RBAC policies to grant wider access.

These are not defects. They define what the system is designed to defend against and where operational controls must compensate.

Infisical Cloud

Managed service at app.infisical.com. Infisical operates PostgreSQL, Redis, and the API layer. All traffic routes through Cloudflare. The team handles upgrades, backups, uptime, and security patches. SOC 2 Type II certified. For most teams, this is the right default: it removes operational overhead and provides enterprise compliance out of the box.

Pricing is per-seat for human users. Machine Identities and API calls are not per-seat. The free tier supports unlimited secrets and environments with 5 member seats and 5 machine identities. Paid tiers start at $6 per seat per month and unlock SCIM provisioning, SAML SSO, and advanced RBAC.

Self-Hosted

Run Infisical on your own infrastructure. The official deployment path is Docker Compose or Helm chart. You bring PostgreSQL and Redis. The API containers connect to your storage. Your reverse proxy handles TLS. Infisical provides the application containers; you provide the substrate.

Self-hosting is worth the operational cost in specific cases: data residency requirements under regulations like GDPR or KDPA 2019 that restrict cross-border data transfer, air-gapped environments where outbound internet is not permitted, or organizations that cannot allow any third party to hold encrypted copies of their secrets even in ciphertext form.

When self-hosting, the siteUrl parameter on the SDK and the --domain flag on the CLI must point to your instance URL. The default https://app.infisical.com will not work. This is a common misconfiguration during initial setup.

Hybrid: Self-Host Infisical, Cloud-Backed Secrets

A third pattern: run the Infisical API yourself but back it with a managed database (Neon, Supabase, AWS RDS). This keeps compute and application data on your infrastructure while offloading database operations to a managed service. The Infisical API does not care where PostgreSQL lives as long as it gets a valid connection string.