Permissions

Understand how instance roles and vault roles control access across Agent Vault.

Need an enterprise-grade solution? Infisical offers managed Agent Vault with enterprise support, SLAs, and advanced features. Book a demo with us to learn more.

Agent Vault separates permissions into two independent axes: instance roles and vault roles. Instance roles control who can manage the Agent Vault server itself (users, agents, global settings, resets). Vault roles control who can operate within a specific vault, approving proposals, managing members, and configuring credentials. The two axes are fully independent, so having one does not imply the other.

Instance roles

Instance-level roles govern administrative operations across the entire Agent Vault instance. Both users and agents have instance-level roles. There are three roles: owner, member, and no-access. The hierarchy is no-access < member < owner.

Capability	Owner	Member	No Access
Instance settings (invite-only, domains)	Yes	No	No
Manage users (list, remove, set-role)	Yes	No	No
Manage agents (create, list, delete, rotate, rename, set-role)	Yes	Yes	No
Create new vaults	Yes	Yes	No
List / delete all vaults	Yes	No	No
See all vaults & join as admin	Yes	No	No
Send test emails	Yes	No	No
Reset instance	Yes	No	No
Access vault contents	Only if member	Only if member	Only if member

The no-access role exists for actors that should have zero instance-scoped capabilities — for example, an agent that should only ever proxy traffic and raise proposals inside a specific vault. A no-access actor can still authenticate, view their own profile, and operate within any vault they’re explicitly granted to (per their vault role). They simply cannot do anything at the instance scope: no creating vaults, no creating other actors, no listing the actor directory.

The label refers specifically to the absence of instance-level access. A no-access actor with a proxy grant on payments can route every request that vault allows; they just can’t go behind the instance-level controls.

Owners can see every vault and join any vault as admin, but they are not automatic members. Until an owner explicitly joins a vault (via agent-vault owner vault join or the web UI), they cannot view its credentials or approve proposals. This lets owners recover orphaned vaults while keeping vault contents access-controlled.

Vault roles

Vault-level roles govern what users and agents can do inside a vault they belong to. There are three roles: admin, member, and proxy.

Capability	Admin	Member	Proxy
Use proxy	Yes	Yes	Yes
Discover services	Yes	Yes	Yes
Raise proposals	Yes	Yes	Yes
View credential names	Yes	Yes	Yes
Set / delete credentials directly	Yes	Yes	No
Approve / reject proposals	Yes	Yes	No
Manage vault services	Yes	Yes	No
Add agents to vault (proxy only)	Yes	Yes	No
Add agents to vault (any role)	Yes	No	No
Invite users to vault	Yes	No	No
Manage vault users (remove, set-role)	Yes	No	No
Manage vault agents (remove, set-role)	Yes	No	No
Delete vault	Yes	No	No

The proxy role is the most restricted, ideal for agents that only need to proxy requests and raise proposals for human review. The member role adds the ability to manage credentials, approve proposals, and configure vault services. The admin role has full control, including inviting users and agents with any role.

Vault admins and members can both review agent proposals. When an agent raises a proposal, vault members receive the approval link (via email if SMTP is configured) and can approve or reject from the browser or CLI.

How the two axes interact

The two permission axes are fully independent. An instance owner who has not joined a vault cannot see its credentials or approve proposals. A vault admin who is not an instance owner cannot manage users or reset the instance.

Example: Alice is an instance owner but has not joined the payments vault. She can see it in her vault list and join it at any time, but she cannot approve proposals or proxy requests through payments until she does. Meanwhile, Bob is a vault admin on payments but a regular instance member. He can approve proposals and manage agents within payments, but he cannot create new users or reset the instance.

The first user

1. Start the server

   bash agent-vault server
2. Register

   The first user to register becomes the instance owner and is automatically granted vault admin on the default vault. bash agent-vault register

3. Start working

   The owner can immediately create agents, set credentials, and configure services on the default vault. No further setup is needed.

A default vault is created automatically at startup. The first user is granted admin on this vault as part of registration.

Change roles

Instance role

Only instance owners can change instance-level roles. Both users and agents can be promoted or demoted.

# Change a user's instance role
agent-vault owner user set-role [e-mail] --role owner

# Change an agent's instance role
agent-vault agent set-role my-agent --role owner

Vault role

Vault admins (and instance owners for any vault) can change vault-level roles.

agent-vault vault user set-role [e-mail] --role proxy --vault my-vault
agent-vault vault agent set-role my-agent --role member --vault my-vault

The last instance owner cannot be demoted. Agent Vault blocks set-role if it would leave the instance with zero owners. This applies across both users and agents.

Owner-level vault operations

Instance owners have a set of cross-vault operations that do not require vault membership:

• See all vaults: Owners see every vault in their vault list, including vaults they have not joined.
• Join any vault: agent-vault owner vault join <name> grants the owner admin access to a vault. Useful for recovering orphaned vaults.
• Delete any vault: agent-vault owner vault delete <name> deletes a vault regardless of membership.
• Manage agents: agent-vault agent list, info, delete, rotate, rename, and set-role are instance-level operations. Any instance member can create agents; vault admins control per-vault agent access.

These operations affect vault existence and agent lifecycle. To access vault contents (credentials, proposals, proxy), the owner must first join the vault.