Liquidity.io Docs

Secrets management, encryption keys, HSM integration, per-org isolation, audit trails

Liquid KMS is the secrets and key management layer for the Liquidity.io platform. All API keys, signing secrets, payment provider credentials, and encryption keys are stored in KMS — never in environment variables, config files, or code.

What KMS Manages

Secret Type	Examples
Payment credentials	Stripe API keys, Plaid secrets, ACH credentials
Signing secrets	Webhook HMAC keys, JWT signing keys
Encryption keys	Per-org root keys, field-level encryption
Certificates	TLS certs, mTLS client certs
SSH credentials	Deploy keys, service account keys
MPC keys	Encrypted key share backups, HSM wrapping keys

Architecture

Application (ATS, Bridge, etc.)
        ↓
    Liquid KMS API
        ├─ Secret Storage (encrypted at rest)
        ├─ Transit Engine (encrypt/decrypt without exposure)
        ├─ Key Registry (metadata, policies, audit)
        └─ Dynamic Secrets (short-lived DB/SSH creds)
              ↓
         HSM Backend (AWS CloudHSM / GCP HSM)

Key Features

Per-Org Isolation

Every organization gets its own root encryption key. Secrets for one org cannot be decrypted by another — even by KMS operators.

Org: Liquidity.io  → Root Key A → encrypts all Liquidity secrets
Org: White-label X → Root Key B → encrypts all White-label X secrets

Transit Engine (Encryption-as-a-Service)

Encrypt and decrypt data without ever exposing the key to the application:

# Encrypt
POST /api/v1/transit/encrypt
{ "plaintext": "sensitive-data", "keyName": "payment-keys" }
→ { "ciphertext": "vault:v1:..." }

# Decrypt
POST /api/v1/transit/decrypt
{ "ciphertext": "vault:v1:...", "keyName": "payment-keys" }
→ { "plaintext": "sensitive-data" }

# Rewrap (rotate without decrypting)
POST /api/v1/transit/rewrap
{ "ciphertext": "vault:v1:...", "keyName": "payment-keys" }
→ { "ciphertext": "vault:v2:..." }

Credential Hydration

Payment provider credentials are fetched from KMS at runtime with caching:

Parameter	Value
Cache TTL	5 minutes
Stale fallback	30 minutes
Providers cached	25+ payment provider fields per org

Shamir Unseal

Root key recovery uses Shamir Secret Sharing over GF(2^8):

Root Key → Split into N shares (e.g., 5)
Recovery requires K shares (e.g., 3)
Shares distributed to separate key holders

Dynamic Secrets

Short-lived credentials for database and SSH access:

Type	TTL	Rotation
PostgreSQL credentials	1 hour	Auto-rotate
SSH certificates	30 minutes	On-demand
Service tokens	24 hours	Auto-rotate

Integration with MPC

KMS and MPC work together for custody:

Layer	Responsibility
KMS (control plane)	Policies, approvals, audit, key lifecycle
MPC (signing plane)	Threshold signatures, no key reconstruction

KMS manages the encrypted backups of MPC key shares
KMS provides per-org wrapping keys for MPC storage
KMS enforces approval workflows for high-value signing operations
MPC handles the actual cryptographic signing — KMS never sees private key material

Access Control

Machine Identities

Services authenticate to KMS via machine identity credentials (client ID + secret pair). Each service gets a dedicated identity with scoped permissions.

Approval Workflows

For sensitive operations (key rotation, secret deletion, high-value signing):

Action	Approval Required
Read secret	Auto-approve (machine identity)
Create secret	Auto-approve
Update secret	Requires approval (configurable)
Delete secret	Requires 2 approvals
Key rotation	Requires admin approval
Export	Blocked (transit-only)

Audit Trail

Every secret access is logged:

{
  "action": "secret.read",
  "secret": "payment/stripe-api-key",
  "identity": "console-service",
  "org": "liquidity",
  "timestamp": "2026-03-20T19:00:00Z",
  "ip": "10.0.1.50",
  "approved": true
}

Live Deployment

Parameter	Value
URL	`https://kms.liquidity.io`
Backend	TypeScript (Fastify)
Storage	PostgreSQL (367+ migrations)
HSM	AWS CloudHSM / GCP HSM
Uptime SLA	99.99%

Liquid KMS — Key Management