Why attribution matters

When a credential is leaked, the first question is always “who had access?” With traditional secret managers, the answer is usually “everyone with the environment variable.” Vault answers this question precisely because every credential access is attributed to a specific identity.

In an AI-assisted development workflow, attribution becomes more important. Multiple agents might access the same credential within the same hour. Without attribution, you cannot distinguish a legitimate access by Claude Code from an unauthorized access by a compromised tool.

Identity types

Vault recognizes two categories of identity:

Human identities are tied to user accounts. When a developer uses the SDK or dashboard, their user ID, email, and session information are recorded.

Agent identities are tied to AI agents and automated processes. When Claude Code requests a credential through the MCP server, Vault records the agent type, session ID, and the purpose declared in the request.

interface HumanIdentity {
  type: 'human';
  userId: string;
  email: string;
  sessionId: string;
}

interface AgentIdentity {
  type: 'agent';
  name: string; // e.g. "claude-code", "cursor", "github-actions"
  sessionId: string;
  purpose?: string; // Why the agent needs this credential
}

How attribution flows

When a credential access occurs, attribution is established at two points:

1. Authentication — The caller authenticates with a token that maps to an identity. For human users, this is a session token from the dashboard or a personal access token. For agents, this is a scoped API token configured during MCP server setup.

2. Lease creation — The identity from authentication is embedded in the lease record. This association is immutable. Even if the token is later rotated or revoked, the lease record retains the original identity.

// The audit log entry for a lease creation
{
  event: "lease.created",
  credentialName: "stripe-api-key",
  identity: {
    type: "agent",
    name: "claude-code",
    sessionId: "sess_abc123",
    purpose: "Calling Stripe API to create a test customer"
  },
  lease: {
    id: "lease_xyz789",
    ttl: "15m",
    expiresAt: "2026-04-24T12:15:00Z"
  },
  timestamp: "2026-04-24T12:00:00Z"
}

Purpose declarations

When an agent requests a credential, it can include a purpose field explaining why the credential is needed. This is optional but recommended. Purpose declarations appear in the audit log and can be used in access reviews to verify that credential usage aligns with the agent’s task.

The MCP server prompts AI agents to declare a purpose naturally as part of the credential request flow. Claude Code, for example, will state what it intends to do with the credential before Vault issues the lease.

Access reviews

The audit log supports filtering by identity, so you can answer questions like:

• Which credentials did claude-code access in the last 24 hours?
• How many leases did user corey@ghoststack.dev create this week?
• Which agents accessed production database credentials?

These queries are available through both the SDK and the dashboard.

Attribution and team sharing

When credentials are shared with a team through ACLs, the attribution still tracks the individual who accessed the credential, not the team. If five developers share access to a credential, the audit log shows which of the five created each lease.