Sharing credentials within a team

Vault credentials belong to a tenant (organization), not to individual users. Any member of the tenant can potentially access any credential, subject to access control policies. ACLs let you control which team members and agents can access which credentials, and what operations they can perform.

Roles

Vault defines four built-in roles, ordered from least to most privileged:

viewer — Can list credentials and see their metadata (names, types, metadata, policies). Cannot create leases or see credential values.

user — Everything a viewer can do, plus creating and renewing leases. This is the role for developers who need to use credentials in their daily work.

manager — Everything a user can do, plus creating, updating, rotating, and revoking credentials. This is the role for team leads who manage the credential inventory.

admin — Full access, including managing ACLs, creating API tokens, configuring tenant settings, and viewing the audit log. Typically reserved for security or platform team members.

Assigning roles

Roles are assigned per user or per API token:

// Invite a team member with the "user" role
await vault.team.invite({
  email: 'alice@example.com',
  role: 'user',
});

// Create an API token with the "user" role for an agent
const token = await vault.tokens.create({
  name: 'claude-code-token',
  role: 'user',
  expiresAt: '2026-07-01T00:00:00Z',
});

Credential-level permissions

Beyond tenant-wide roles, you can set per-credential permissions that restrict which identities can access specific credentials. This is configured through the credential’s policy:

await vault.credentials.create({
  name: 'prod-db-url',
  type: 'database-url',
  value: 'postgresql://...',
  policy: {
    defaultLeaseTTL: '30m',
    maxLeaseTTL: '2h',
    allowedIdentities: [
      { type: 'human', email: '*@example.com' },
      { type: 'agent', name: 'deploy-agent' },
    ],
  },
});

The allowedIdentities field accepts patterns. In this example, any human user with an @example.com email and the deploy-agent agent can lease this credential. All other identities are denied, even if they have the user role at the tenant level.

Scoped API tokens

API tokens can be scoped to specific credentials or credential patterns:

const token = await vault.tokens.create({
  name: 'analytics-agent-token',
  role: 'user',
  scope: {
    credentials: ['staging-db-readonly', 'analytics-api-key'],
  },
});

A token with this scope can only create leases for the two named credentials, regardless of the tenant-level role. This is the recommended approach for AI agents: create a dedicated token per agent, scoped to exactly the credentials that agent needs.

Wildcard scopes

For larger teams, managing individual credential names in token scopes becomes tedious. Vault supports wildcard patterns:

const token = await vault.tokens.create({
  name: 'staging-agent-token',
  role: 'user',
  scope: {
    credentials: ['staging-*'],
  },
});

This token can access any credential whose name starts with staging-. Combined with a consistent naming convention, wildcard scopes make it straightforward to manage access across environments.

Viewing effective permissions

To check what a specific identity can access:

const permissions = await vault.team.getPermissions({
  email: 'alice@example.com',
});

// Returns:
// {
//   role: "user",
//   credentials: [
//     { name: "staging-db-url", canLease: true },
//     { name: "prod-db-url", canLease: false, reason: "not in allowedIdentities" },
//   ]
// }

Audit trail for permission changes

Every role assignment, token creation, and ACL change is recorded in the audit log. This includes who made the change, what changed, and when. Permission changes are logged as acl.updated, token.created, and team.invited events.

Best practices

• Use the principle of least privilege. Start with viewer and promote as needed.
• Create dedicated API tokens for each AI agent, scoped to the credentials that agent actually uses.
• Use naming conventions (prod-*, staging-*, dev-*) combined with wildcard scopes to simplify permission management.
• Review the audit log monthly to identify unused tokens and overly broad permissions.
• Set expiration dates on API tokens. A token that never expires is a token you will forget about.