Vault

The Vault stores third-party credentials (API keys, OAuth tokens, database passwords, etc.) that your agent needs at runtime. Credentials are encrypted at rest using AES-256-GCM.

How It Works

Store:   User adds credential → Server encrypts with master key → Stores ciphertext
Retrieve: Agent calls vault.get → Server decrypts → Returns plaintext to agent

The server encrypts/decrypts using a master key (VAULT_MASTER_KEY). Credentials are never stored in plaintext.

Credential Types

Type	Secret Fields	Metadata
`LOGIN`	password	uri, username
`API_KEY`	key	service, prefix
`OAUTH`	accessToken, refreshToken	provider, scopes, expiresAt
`TOTP`	secret (base32 seed)	issuer, account, algorithm
`SSH_KEY`	privateKey, passphrase	publicKey, keyType
`DATABASE`	password, connectionString	engine, host, port, database
`SMTP`	password	host, port, username, encryption
`AWS`	secretAccessKey, sessionToken	accessKeyId, region
`CERTIFICATE`	privateKey	certificate, chain, domain, expiresAt
`CUSTOM`	any key-value pairs	any key-value pairs

Each credential is stored as one encrypted JSON blob. Secret fields go in data (encrypted), non-secret fields go in metadata (plaintext, for display).

Scopes

Scope	Allows
`vault:read`	List credentials, retrieve decrypted values
`vault:write`	Store, update, and delete credentials

MCP Tools

Tool	Scope	Description
`vault.list`	`vault:read`	List all credentials (metadata only)
`vault.get`	`vault:read`	Get decrypted credential by name
`vault.store`	`vault:write`	Store or update a credential
`vault.delete`	`vault:write`	Delete a credential

API Endpoints

Method	Path	Scope	Description
`GET`	`/v0/vault`	`vault:read`	List credentials (metadata)
`GET`	`/v0/vault/:name`	`vault:read`	Get decrypted credential
`PUT`	`/v0/vault/:name`	`vault:write`	Store/update credential
`DELETE`	`/v0/vault/:name`	`vault:write`	Delete credential

Example: Store an API Key

curl -X PUT https://api.mailgent.dev/v0/vault/stripe \
  -H "Authorization: Bearer mgent-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "API_KEY",
    "data": { "key": "sk_live_abc123..." },
    "metadata": { "service": "stripe", "prefix": "sk_live_...c123" }
  }'

Example: Retrieve a Credential

curl https://api.mailgent.dev/v0/vault/stripe \
  -H "Authorization: Bearer mgent-your-api-key"

Returns the decrypted data along with metadata.

Security

Encrypted at rest — AES-256-GCM with authenticated encryption
Per-credential IV — each credential has its own random initialization vector
Tamper-proof — GCM auth tag prevents ciphertext modification
Scoped access — credentials are isolated per identity
Usage tracking — lastUsedAt updated on every retrieval

On this page