Secrets and encryption

How VeloPhex encrypts assets and credentials, delivers them to Robots, and how you rotate the keys.

Secrets in VeloPhex are Secret and Credential assets, credential store configuration, SMTP and storage passwords, identity provider client secrets and webhook signing secrets. They are encrypted before they reach the database, are never returned by the API after you save them, and reach a running automation only for the moment it needs them.

Envelope encryption#

VeloPhex uses two layers of keys:

Key What it protects Where it lives
Key-encryption key (KEK) Wraps every tenant's data key Your deployment configuration (VELOPHEX_KEK, identified by VELOPHEX_KEK_ID, k1 by default)
Tenant data key Encrypts that tenant's secret values The database, wrapped by the KEK

Values are encrypted with AES-256-GCM. The associated data binds each ciphertext to its tenant, key and purpose, so a value copied to another row or tenant fails to decrypt instead of being read in the wrong place.

Every tenant also gets a built-in credential store named Orchestrator, which holds its credentials under this scheme.

Escrow the KEK before you store anything

Without the KEK every stored asset and credential is unrecoverable, including from backups. Put VELOPHEX_KEK, VELOPHEX_KEK_ID and VELOPHEX_TOKEN_PEPPER in your organization's secret escrow before the first tenant stores a credential. Production refuses to start with the development key.

The KEK is read from configuration at start. Custody of the KEK in an external key management service is not part of the current release; keep the configuration file readable only by the account that runs Docker (chmod 600 .env).

How a secret reaches a job#

A job claim never carries a password. Instead:

  1. The Robot claims a job. The claim names a credential lease for the run-as account but carries no secret.
  2. Just before launch, the Robot redeems the credential lease (POST /api/v1/robot/credential-leases/{leaseId}). The lease is bound to that job attempt, to the Robot's lease on it, and to one intended use. Every refusal answers 404 alike, and every redemption is audited.
  3. The Robot passes the value to the executor. It is never persisted and never logged.

Inside a running automation, the Runtime API resolves secrets with the attempt's execution token, and only when the job's run-as identity may read them (see Robot identity and tokens). For example, the Python SDK returns a credential password through runtime.secret("<credential>.password"), and resolve_secret returns a value that prints as **********. See the Python SDK API reference.

Protection on the Robot#

  • The Robot's own secrets (its private key and connection) are stored with DPAPI, LocalMachine scope with entropy, in files whose ACL admits only SYSTEM and Administrators.
  • The service refuses to start if it cannot harden its state folder ACLs.
  • Every log line passes through a secret redactor before it is written.
  • Sensitive workflow state in the engine's local store is DPAPI-protected.

Encryption in transit#

The bundled Caddy front door terminates TLS with an automatic Let's Encrypt certificate, an internal CA (VELOPHEX_TLS=tls internal) or your own certificate. The API sends HSTS on HTTPS requests. Studio and the Assistant refuse to send a token to a plain http address other than localhost.

Encryption at rest#

Application-level encryption covers secret values. Everything else in the database and the blob store (job history, logs, package bytes) is protected by your storage: use encrypted volumes, encrypted managed PostgreSQL, or server-side encryption on your S3-compatible or Azure Blob store.

Rotate a tenant's data key#

Use this when a tenant administrator leaves, or on the tenant's own schedule. It re-encrypts that tenant's secrets under a fresh data key.

  1. Use an account or token with tenant.edit in the tenant.
  2. Call the API:
HTTPCopy
POST /api/v1/tenants/{tenantId}/secret-keys/rotate

Verify: the rotation is recorded in the tenant's audit log. Use one credential asset in a job to confirm it still resolves.

Rotate the KEK#

A KEK rotation re-wraps the data keys only. No ciphertext is rewritten, so it is quick.

Prerequisites: shell access to the Docker host, platform administrator rights, and a fresh backup.

  1. Generate a new key and escrow it next to the current one:

    BashCopy
    openssl rand -base64 32
  2. Add it to velophex.prod.env and point .env at it, keeping the old key configured:

    velophex.prod.envINICopy
    Secrets__KeyEncryptionKeys__k2=<new key>
    .envINICopy
    VELOPHEX_KEK_ID=k2
  3. Recreate the API container:

    BashCopy
    docker compose -f docker-compose.core.yml up -d api
  4. As a platform administrator, re-wrap every data key:

    HTTPCopy
    POST /api/v1/platform/secret-keys/rewrap

    The response is the number of data keys re-wrapped.

  5. In a later change, after you confirm no data key still references k1, remove the old key from configuration.

Remove the old key last

Removing k1 before every data key is re-wrapped makes the affected assets unreadable. The error appears as a decryption failure when a value is read, not at start.

Verify: existing credentials still resolve in a test job after step 4.

Next steps#

Envelope encryption

How a secret reaches a job

Protection on the Robot

Encryption in transit

Encryption at rest

Rotate a tenant's data key

Rotate the KEK

Next steps