Agent registry

Beta feature

Beta functionality is stable but possibly incomplete and subject to change. We strongly discourage using beta features in production deployments of Vault.

Enterprise

Appropriate Vault Enterprise license required

The Agent registry is a Vault Enterprise component that provides enrollment, governance, and auditing for agentic identities. It operates alongside the Identity secrets engine to distinguish agents from other types of Vault clients and to enforce authorization constraints specific to agentic workflows.

Relationship to Vault identities

Every registered agent maps to exactly one Vault identity entity. The entity carries authentication bindings, aliases, and baseline policy attachments, just as it does for any other Vault client. The agent registry adds a record that captures governance metadata and authorization constraints that are specific to agents.

The two components have distinct responsibilities:

Component	Responsibility
Vault identity, including entities and aliases	Authentication binding, baseline policy attachment, group membership
Agent registry record	Agent enrollment, authorization ceiling, ownership, description

An entity can exist without an agent registry record. In that case, the entity represents a non-agent client and is not subject to agent-specific governance. An agent registry record cannot exist without a corresponding entity.

Agent registry records

Agent registry records contain the following fields:

Field	Description
`id`	Unique identifier for the agent registry record, generated by Vault.
`display_name`	Human-readable name for the agent. Must be unique within the namespace. A nonempty value for this field is required.
`entity_id`	The Vault identity entity that the registration governs.
`description`	Optional description of the agent's purpose.
`owner`	Optional identifier for the person or team responsible for the agent.
`ceiling_policies`	List of policy names that define the agent's authorization ceiling, used to limit permissions only in on-behalf-of requests.
`no_default_ceiling_policy`	When `true`, Vault does not automatically add default ceiling policies to the registration.
`optional_authorization_details`	When `true`, makes the `authorization_details` claim optional for the registered agent.
`creation_time`	Timestamp of when the registration was created.
`last_updated_time`	Timestamp of the most recent update to the registration.

Agent registry invariants

The agent registry enforces the following rules:

One registration per entity. Each entity can have at most one registration record. If you need to re-register an entity, delete the existing registration first.
Entity must exist. The entity_id must refer to an existing Vault Identity entity at the time the registration is created or updated.
Display name must be unique within the namespace. No two registrations in the same namespace can share a display_name.

Authorization ceiling

The authorization ceiling is the primary governance mechanism the agent registry provides. It restricts what an agent can do when it acts on behalf of another identity in a delegation, or on-behalf-of, flow.

The authorization ceiling for an agent cannot expand what an agent is allowed to do. In a delegated workflow, Vault evaluates two policy sets independently:

The subject's baseline policies must allow the request.
The agent's ceiling policies must also allow the request.

If either policy set denies the operation, Vault denies the request. The ceiling can only further restrict operations that the baseline access would otherwise permit. It can never grant additional access.

Default ceiling policies

When you create or update a registration, Vault automatically adds two built-in policies to ceiling_policies unless you set no_default_ceiling_policy to true:

default — Vault's standard default ACL policy.
default-ceiling — A narrow policy that permits the agent to read its own agent registry record and the definitions of the default and default-ceiling policies.

These defaults ensure that an agent acting on behalf of a subject cannot use the subject's permissions to modify the agent's own governance constraints.

If you set no_default_ceiling_policy to true, Vault does not add either policy automatically. You can still include them explicitly in ceiling_policies if you want one or both.

Define policies specific to the access your agent requires, then add them to the agent's ceiling_policies.

Note

The ceiling_policies field cannot contain the root policy.