AI agents need credentials. They need API keys to call external services, OAuth tokens to act on behalf of users, SMTP passwords to send email, and database connection strings to store data. The question is where those credentials live and who can access them.
AgenticMail Enterprise handles this with a secure vault system that encrypts credentials at rest, scopes them by organization, and resolves them automatically when agents need them.
The Problem With Environment Variables
The obvious approach is environment variables. Dump everything into .env, load it at startup, and reference process.env.WHATEVER when needed. This works for a single deployment with a handful of secrets. It falls apart when multiple organizations share infrastructure, each with their own API keys, and agents should only access credentials they’ve been explicitly granted.
Environment variables are flat. They have no scoping, no access control, no audit trail of who read what and when. They’re also visible to every process on the machine. For enterprise deployments where tenant isolation matters, this isn’t acceptable.
How the Vault Works
The vault encrypts every credential using AES 256 before writing it to storage. The encryption key is derived from a master key that’s provided at startup and never persisted to disk. If the process restarts, the master key must be supplied again (from a hardware security module, a key management service, or manual entry for smaller deployments).
Each credential is stored with metadata: a name, a type classification (API key, OAuth token, password, certificate, connection string), the owning organization, an optional expiration timestamp, and a list of agent IDs authorized to read it.
The storage backend is pluggable. The vault can write to the same database the rest of the system uses, to a dedicated secrets store, or to an encrypted file on disk. The encryption happens before the data reaches the storage layer, so even if someone gains direct database access, the credentials are unreadable without the master key.
Org Scoped Namespacing
Every credential belongs to an organization. Agents in Organization A cannot see or access credentials belonging to Organization B, even if they share the same deployment. The namespace is enforced at the vault level, not just at the API level. Even a bug in the API routing layer can’t leak credentials across organizations because the vault itself checks the requesting agent’s org membership before decrypting anything.
Namespacing also prevents collisions. Two organizations can both have a credential named “openai_api_key” without conflict. The vault resolves names within the context of the requesting org.
Automatic Credential Resolution
This is where the vault integrates with the tool adapter pattern. When an agent invokes a tool (say, a Slack integration or a calendar API), the tool adapter checks what credentials that tool requires. It then requests those credentials from the vault on behalf of the agent.
The agent itself never sees raw credential values. The tool adapter receives the decrypted credential, uses it to make the external API call, and discards it from memory when the call completes. The agent only sees the result.
This pattern means agents can be given access to tools without ever handling secrets directly. You grant an agent permission to use the “send Slack message” tool, and the vault ensures the Slack OAuth token is available to the tool adapter when it executes. The agent’s prompt, its conversation history, and its logs never contain credential material.
Rotation and Expiration
Credentials can have expiration dates. The vault runs a background check that flags credentials approaching expiration and notifies administrators. For OAuth tokens with refresh capabilities, the vault can automatically rotate tokens before they expire, updating the stored value without any agent downtime.
When a credential is rotated (manually or automatically), every subsequent tool invocation picks up the new value. There’s no cache invalidation problem because the vault is always the source of truth, and credentials are read fresh for each tool execution.
Audit Trail
Every vault operation is logged. Every read, write, update, and deletion gets an audit entry with the timestamp, the requesting agent or user, the credential name (but never the credential value), and the operation result. These audit logs feed into the same audit system that tracks all other privileged operations in the platform.
For compliance scenarios where you need to prove that a specific credential was only accessed by authorized entities during a specific time window, the audit trail provides that evidence.
Why This Matters
Giving AI agents access to credentials is inherently risky. They process untrusted input, generate unpredictable output, and operate with significant autonomy. The vault ensures that even if an agent is compromised, the blast radius is contained. It can only access credentials it’s been explicitly granted, it never sees raw values, and every access is logged.
Security isn’t a feature you bolt on later. It’s infrastructure you build first.
Source Code
The SecureVault.encrypt method shows the full encryption pipeline: salt and IV generation, PBKDF2 key derivation with 600K iterations, and AES 256 GCM authenticated encryption:
export class SecureVault {
encrypt(plaintext: string): string {
const salt = randomBytes(this.config.saltLength);
const iv = randomBytes(this.config.ivLength);
const key = this.deriveKey(salt); // PBKDF2, 600K iterations
const cipher = createCipheriv('aes-256-gcm', key, iv, {
authTagLength: this.config.authTagLength,
});
const encrypted = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
const tag = cipher.getAuthTag();
return JSON.stringify({ v: 1, alg: 'aes-256-gcm', salt, iv, tag, data: encrypted });
}
}