Docs

Encryption architecture

All API key values are encrypted at rest with AES-256-GCM before reaching the database. ApiVault provides two encryption models: server-managed default encryption and zero-knowledge custom vault encryption.

Encryption Modes

You can configure your personal vault encryption mode in Settings → Encryption Key, or configure a collaborative workspace's encryption in [Project] → Vault Encryption.

Default mode

Secrets are encrypted using server-managed cryptographic keys. No custom vault key is required to reveal keys — your authenticated session (or CLI/MCP token with appropriate scope) is sufficient. Decryption takes place securely on the backend when authorized.

Custom mode (Zero-Knowledge)

You set a personal or team custom vault key that ApiVault never stores. Secrets are encrypted with a key derived from your custom vault key. Decrypt operations strictly require the vault key via:

  • Web UI vault key prompt when clicking reveal or export
  • CLI: --vault-key flag, APIVAULT_KEY environment variable, apivault config set vaultKey, or interactive prompt
  • MCP: vault_key parameter on reveal_key, add_key, and update_key tools

Key Derivation & Rotation

Custom vault keys use a unique salt and a memory-hard derivation, so a guessed key is slow to test.

  • Minimum length: New custom vault keys must be at least 16 characters. Legacy custom vaults remain readable with their existing derivation until rotated.
  • Salt and derivation: Setting or rotating a custom vault key generates a fresh random 32-byte salt, and the key is derived from it with scrypt.
  • Atomic re-encryption: Switching between modes, changing your vault key, or rotating the key decrypts and re-encrypts all existing keys in a single atomic database transaction. If any secret fails to re-encrypt, the entire operation rolls back.

Cipher Specification

ApiVault uses AES-256-GCM (Galois/Counter Mode), an authenticated symmetric cipher providing both confidentiality and data integrity:

  • Key size: 256-bit derived key.
  • Initialization Vector (IV): A random 128-bit IV generated fresh for every encryption operation.
  • Authentication Tag: 128-bit authentication tag ensuring any tampering with ciphertext causes immediate decryption failure.

Data Storage & Network Isolation

ApiVault stores encrypted key payloads, initialization vectors, and non-sensitive metadata (key name, service category, environment label, optional notes) in a relational MySQL database managed via Prisma.

Secret values are never stored in plaintext. The CLI and MCP server communicate with ApiVault strictly over TLS/HTTPS — client tools never access the database directly.