Vault

Encrypted secrets management — securely store API keys, passwords, and credentials used by your agents.

Overview
How It Works
Key Concepts
Managing Secrets
Platform Presets
Secret Categories
Key Rotation
Audit Log
Vault Status
Configuration & Setup
Best Practices
Troubleshooting
Related Pages

Overview

For everyone: The Vault is a secure safe for all the passwords and API keys your AI agents need. Instead of putting credentials directly in agent configs (where they could be leaked), you store them in the Vault. The Vault encrypts everything so even if someone accesses the database, they can't read your secrets. Every time anyone looks at or changes a secret, it's logged.

For technical users: The Vault implements AES-256-GCM authenticated encryption with PBKDF2 key derivation (100,000 iterations). Each secret gets a unique random salt and initialization vector. The master encryption key is derived from AGENTICMAIL_VAULT_KEY in the .env file. Platform presets auto-name secrets as skill:<platform>:<key> for automatic discovery by agent tools. Full audit trail via /vault/audit-log.

Organization Scoping: Use the org switcher in the page header to view and manage vault secrets per organization. Secrets are scoped — each organization has its own isolated vault.

How It Works

Store a secret — select a platform preset or create a custom secret. The value is encrypted before being written to the database.
Agents use secrets — agent tools automatically discover secrets named skill:<platform>:<key> and decrypt them on demand.
Access is logged — every read, create, delete, and rotate operation is recorded in the audit trail.
Rotate periodically — re-encrypt secrets with fresh salts and IVs without changing the actual credential value.

Key Concepts

Encryption Details

Property	Value
Algorithm	AES-256-GCM (authenticated encryption with tamper detection)
Key Derivation	PBKDF2 with 100,000 iterations
Salt	Unique random salt per secret
IV	Unique random initialization vector per secret
Master Key	Derived from `AGENTICMAIL_VAULT_KEY` environment variable

Secret Naming Convention

Platform preset secrets follow the naming pattern skill:<platform>:<key>:

skill:openai:access_token
skill:anthropic:access_token
skill:stripe:access_token
skill:stripe:webhook_secret
skill:aws:access_key_id
skill:aws:secret_access_key

Agent tools automatically discover and use secrets matching this pattern.

Managing Secrets

Adding Secrets

Click "Add Secret" to open the modal:

Select Platform/Service — choose from presets or "Custom Secret."
Fill in fields — each platform has specific fields (API key, token, etc.). Required fields are marked with *.
Click "Store Secret" — the value is encrypted and saved.

Viewing Secrets

Click any secret in the table (or the eye icon) to open the view modal:

Secret metadata: category, created by, created date, last rotated date.
Reveal/hide toggle — click the eye icon to show the decrypted value.
Copy button — copies decrypted value to clipboard.
Every view is logged in the audit trail.

Warning: Viewing a secret creates an audit log entry. Be mindful of who has access to view secrets in production.

Deleting Secrets

Click the trash icon and confirm. Deletion is permanent and immediately revokes access for any services using the secret.

Danger: Deleting a secret cannot be undone. Any agents or services using the secret will immediately lose access. Make sure the credential is no longer needed before deleting.

Searching and Filtering

Search bar — search by name, category, or creator.
Category filter — filter by Deploy Credentials, Cloud Storage, API Key, Skill Credential, or Custom.

Platform Presets

The Vault includes presets for common platforms. Each preset auto-configures the secret name, category, and required fields:

Platform	Category	Fields
OpenAI	Skill Credential	API Key (`sk-...`)
Anthropic	Skill Credential	API Key (`sk-ant-...`)
Google Cloud / Gemini	Skill Credential	API Key, OAuth Client ID, OAuth Client Secret
ElevenLabs	Skill Credential	API Key (`xi_...`)
Telegram Bot	Skill Credential	Bot Token
Slack	Skill Credential	Bot Token (`xoxb-...`), Signing Secret*
GitHub	Skill Credential	Personal Access Token (`ghp_...`)
Stripe	Skill Credential	Secret Key (`sk_live_...`), Webhook Secret*
SendGrid	Skill Credential	API Key (`SG...`)
Twilio	Skill Credential	Account SID (`AC...`), Auth Token
AWS	Cloud Storage	Access Key ID (`AKIA...`), Secret Access Key, Region*
Cloudflare	Skill Credential	API Token, Account ID*
Notion	Skill Credential	Integration Token (`secret_...`)
HubSpot	Skill Credential	Private App Token (`pat-...`)
SMTP / Email	Deploy Credentials	Host, Port*, Username, App Password
Database	Deploy Credentials	Connection String

* = optional field

Secret Categories

Category	Color	Description
Deploy Credentials	Indigo	Infrastructure and deployment secrets (SMTP, database connections)
Skill Credentials	Green	API keys for agent tools (OpenAI, Slack, GitHub, etc.)
Cloud Storage	Blue	AWS, GCP, and other cloud provider credentials
API Keys	Amber	General-purpose API keys
Custom	Gray	User-defined secrets with custom names

Key Rotation

Rotating a secret re-encrypts it with a fresh salt and initialization vector without changing the actual credential value. This limits the window of exposure if encryption material is compromised.

Single Secret Rotation

Click the rotate icon on any secret, or use the "Rotate" button in the view modal.

Bulk Rotation

Click "Rotate All" to re-encrypt every secret in the vault at once. Use after security incidents or as periodic hygiene.

Tip: Rotate secrets periodically (monthly or quarterly). Use "Rotate All" immediately after any suspected security incident.

Audit Log

The Audit Log tab records every vault operation. Each entry includes:

Field	Description
Action	encrypt, decrypt, delete, rotate, migrate, read, create
Secret	Name or ID of the secret accessed
Actor	User or system that performed the action
Timestamp	When the action occurred
Details	Additional metadata (IP address, etc.)

Features:

Search — search across all fields
Action filter — filter by specific action types
Pagination — 25 entries per page with full navigation
Click to expand — view full metadata including IP address and entry ID

Vault Status

The Status tab shows:

Vault Status — Active or Not Configured
Total Secrets — count of stored secrets
Encryption method — AES-256-GCM
Key Derivation — PBKDF2
Secrets by Category — breakdown chart showing how many secrets are in each category

Configuration & Setup

API Endpoints

Method	Endpoint	Description
GET	`/vault/secrets?orgId=`	List all secrets (metadata only, not decrypted)
POST	`/vault/secrets`	Create/encrypt a new secret
GET	`/vault/secrets/:id`	Decrypt and retrieve a secret value
DELETE	`/vault/secrets/:id`	Permanently delete a secret
POST	`/vault/secrets/:id/rotate`	Re-encrypt a single secret
POST	`/vault/rotate-all`	Re-encrypt all secrets
GET	`/vault/audit-log`	Query audit log (supports search, action filter, pagination)
GET	`/vault/status`	Vault status and statistics

Create Secret Request

POST /vault/secrets
{
  "orgId": "org-123",
  "name": "skill:openai:access_token",
  "value": "sk-...",
  "category": "skill_credential"
}

Best Practices

Use platform presets — they auto-configure naming so agent tools can discover credentials automatically.
Rotate regularly — monthly rotation limits cryptographic exposure.
Review audit logs — check for unexpected decrypt operations, especially from unfamiliar actors.
Limit vault access — use the Users page to restrict which users can access the Vault page.
Back up VAULT_KEY — without this environment variable, all secrets are permanently unrecoverable.
Use Rotate All after incidents — if any encryption material may have been compromised, rotate everything immediately.
Don't duplicate secrets — if a platform needs multiple credentials (e.g., Stripe key + webhook secret), the preset handles this automatically.
Prefer vault over inline config — never put credentials directly in agent configurations. Always use the vault.

Troubleshooting

"Decryption failed" when viewing a secret

The AGENTICMAIL_VAULT_KEY in your .env may have changed or been corrupted. If you migrated to a new machine, ensure you copied the exact same .env file. Secrets encrypted with a different key cannot be recovered.

Agent can't find credentials

Verify the secret follows the skill:<platform>:<key> naming convention. Check the secret name in the vault list — it must match exactly what the agent tool expects.

"Vault not configured" status

The AGENTICMAIL_VAULT_KEY environment variable is missing. Add it to ~/.agenticmail/.env and restart the server.

Audit log shows unexpected access

Check the actor column for the user or system that accessed the secret. Review user permissions on the Users page and consider restricting Vault access to fewer users.

Bulk rotation fails partway

Some secrets may have been rotated while others weren't. Check the audit log for which secrets were rotated successfully, then manually rotate the remaining ones.

Users — Control who can access the Vault. DLP — Prevents agents from leaking credentials stored in the Vault. Compliance — Vault audit logs feed into SOC2 and audit reports. Database Access — Database credentials can be stored in the Vault. Domain & Deployment — VAULT_KEY migration is critical during server moves.

AgenticMail Enterprise Documentation Report an issue

Vault

Table of Contents

Overview

How It Works

Key Concepts

Encryption Details

Secret Naming Convention

Managing Secrets

Adding Secrets

Viewing Secrets

Deleting Secrets

Searching and Filtering

Platform Presets

Secret Categories

Key Rotation

Single Secret Rotation

Bulk Rotation

Audit Log

Vault Status

Configuration & Setup

API Endpoints

Create Secret Request

Best Practices

Troubleshooting

"Decryption failed" when viewing a secret

Agent can't find credentials

"Vault not configured" status

Audit log shows unexpected access

Bulk rotation fails partway

Related Pages