Security model

Last updated at August 13, 2026

ApiVault is built for developers who read the security model. This page covers encryption, authentication, session management, and best practices across all integration surfaces.

Encryption

All API key values are encrypted at rest before storage. ApiVault supports two encryption modes, configured in Settings → Encryption Key.

Default mode

Secrets are encrypted using server-managed keys. No passphrase is required to reveal keys — your authenticated session (or CLI/MCP token with appropriate scope) is sufficient.

Custom mode

You set a personal vault passphrase (vault key) that ApiVault never stores. Secrets are encrypted with a key derived from your passphrase. Decrypt operations require the passphrase via:

Web UI vault key prompt
CLI: --key, APIVAULT_KEY, config vaultKey, or interactive prompt
MCP: vault_key parameter on reveal_key, add_key, update_key

Vault key cannot be recovered

If you forget your custom vault passphrase, encrypted keys cannot be decrypted. You can only delete them and re-add with a new passphrase. Store your vault key securely — a password manager is recommended.

You can switch between modes, change your vault key, or disable custom encryption from the encryption settings page. Changing or disabling custom encryption requires your current vault passphrase and re-encrypts existing keys.

Authentication

The web app supports multiple authentication methods:

Method	Description
Google OAuth	Sign in with your Google account. Manage linked accounts in Settings → OAuth Connections.
Email & password	Traditional credentials. Set or change password in Settings → Security & MFA.
Passkeys	WebAuthn passkeys for passwordless sign-in (Touch ID, Face ID, Windows Hello, hardware keys).
TOTP 2FA	Time-based one-time passwords via an authenticator app. Can be required after initial setup.

Enable MFA early

Turn on TOTP or a passkey in Settings → Security & MFA as soon as your account is set up. MFA protects vault access even if your email password is compromised.

Passkeys can also serve as a second factor when MFA is enabled.

Sessions & tokens

ApiVault uses three independent credential types. Revoking one does not affect the others:

Credential	Used by	Revoke via
Browser session	Web dashboard, settings	Settings → Sessions & Devices, or sign out
CLI token	`apivault` commands	`apivault logout` or Settings → Sessions & Devices
MCP OAuth token	Cursor, Claude, MCP clients	Settings → MCP Connections

Review active sessions regularly

Revoke browser sessions, CLI tokens, and MCP connections you no longer recognize from Settings → Sessions & Devices and Settings → MCP Connections. Stale credentials are a common path to unauthorized vault access.

CLI security

Browser-based pairing — CLI auth uses a one-time browser approval flow. No passwords are typed in the terminal.
Local token storage — tokens are stored in ~/.apivault/token.json with owner-only permissions on Unix.
Dotenv isolation — apivault run temporarily hides local .env files so injected vault secrets take precedence.
No secrets in shell history — prefer config set vaultKey (hidden prompt) or APIVAULT_KEY over typing passphrases inline.

Prefer run over export

Use apivault run to inject secrets into a process instead of writing decrypted values to a .env file on disk. Fewer files means fewer leak paths.

MCP security

Scoped OAuth — agents receive only the permissions you approve (keys:read, keys:write, keys:reveal).
Least privilege — grant read-only scopes when agents only need to browse keys; avoid keys:reveal unless necessary.
Short-lived access tokens — MCP access tokens expire after 1 hour; refresh tokens last 30 days.
Revocable connections — each MCP client appears separately in Settings → MCP Connections.

Treat keys:reveal as high risk

The keys:reveal scope lets an agent read raw secret values. Only grant it when the agent truly needs plaintext keys, and revoke the connection when the task is done.

See MCP Integration → Security practices for agent workflow guidance.

Best practices

Never commit ~/.apivault/, exported .env files, tokens, or vault passphrases
Add .env and .env.local to .gitignore
Use custom encryption mode for an extra layer of zero-knowledge protection
Enable 2FA and passkeys on your account
Review and revoke stale CLI and MCP connections periodically
Use apivault run instead of exporting secrets to disk when possible
Do not paste raw secrets into chat, commits, logs, or issue trackers
Request minimum MCP scopes for AI agents

Keep secrets out of git

Add .env, .env.local, and any exported dotenv files to .gitignore before your first commit. A single accidental push exposes every key in that file permanently in git history.

Data storage

ApiVault stores encrypted key values, metadata (name, service, environment, notes), and account data in a MySQL database via Prisma. Secret values are never stored in plaintext. The CLI and MCP server communicate with ApiVault over HTTPS only — they never access the database directly.

Was this page helpful?