Managing AI Agent Credentials with Anima Vault

AI agents often require access to third-party services, necessitating the secure storage of sensitive credentials. Hardcoding these or using insecure environment variables creates significant risk. Anima Vault provides a dedicated infrastructure for managing these secrets at scale.

Scoping Credentials to Agent Identities#

The core principle of Anima Vault is identity-based access control. Secrets are never stored globally; they are scoped to specific agent identities. This ensures that an agent only has access to the credentials it explicitly needs for its assigned tasks.

import { Anima } from "@anima-labs/sdk";
 
const anima = new Anima({ apiKey: process.env.ANIMA_API_KEY! });
 
const agent = await anima.agents.get("agent_123");
 
// Store a credential in the agent's vault
const credential = await anima.vault.createCredential({
  agentId: agent.id,
  type: "api_key",
  name: "OpenAI",
  apiKey: {
    provider: "openai",
    key: "sk-proj-..."
  }
});

Secure Retrieval and Injection#

The important part is that the agent never needs the plaintext. useCredential makes the outbound call server-side with the secret attached, and returns you the upstream response with the credential scrubbed out. The key is never in your process, so it cannot reach a log line, a stack trace, or a model's context window.

// Use the credential without ever reading it
const response = await anima.vault.useCredential(credential.id, {
  agentId: agent.id,
  method: "POST",
  url: "https://api.openai.com/v1/chat/completions",
  body: JSON.stringify({ model: "gpt-4o", messages })
});
 
console.log(response.status, response.body);

Any Authorization header you pass is ignored and replaced, and the destination host must be on the credential's allowlist — so a compromised agent cannot redirect a working credential at an endpoint of its choosing.

Reading a secret back is a separate, audited action rather than the default path. If you genuinely need the plaintext, getCredential returns it masked unless you explicitly ask to reveal, and the reveal is written to the audit trail.

Generating a secret the agent never sees#

There is no scheduled-rotation engine today — rotation is something you drive, and the vault's job is to make the new secret exist without it passing through your code. generatePassword creates the value and stores it in one call, so there is no window where the plaintext sits in a variable you have to remember not to log.

const dbCredential = await anima.vault.generatePassword({
  agentId: agent.id,
  name: "Primary database",
  login: { username: "agent_service" }
});

From there the agent authenticates through useCredential exactly as above, and rotating means generating a new one and updating the upstream system — not handing the agent a secret to hold.

Audit Logging and Compliance#

Every access request to the vault is logged. This provides a complete audit trail of when and where an agent used a particular credential. Compliance reports can be generated per identity or per organization.

for await (const entry of anima.vault.audit({ agentId: agent.id, limit: 100 })) {
  // action is one of: access, store, delete, broker_use, broker_use_denied
  console.log(`${entry.createdAt}: ${entry.action} on ${entry.credentialId}`);
}

Note broker_use and broker_use_denied in that list. Because the agent goes through useCredential rather than reading the secret, the audit trail records each individual use of a credential — not just the one moment it was read out, after which the platform loses sight of it.

Best Practices for Agent Vaults#

• Use the Principle of Least Privilege: Only grant an agent access to the minimum set of credentials required for its function.
• Enable MFA for Human Administrators: While agents use API keys, ensure that humans managing the vault have Multi-Factor Authentication enabled.
• Avoid Long-Lived Credentials: Prefer OAuth token credentials. Their access tokens are refreshed before expiry from the stored refresh token, controlled by autoRefresh (on by default). API keys have no equivalent — as above, rotating one means generating a replacement and updating the upstream system yourself.
• Regularly Rotate Root Keys: The master keys used to encrypt the agent's vault should be rotated according to your organization's security policy.

By centralizing secret management within the Anima infrastructure, you reduce the attack surface and simplify the deployment of autonomous AI agents across diverse environments.