Agent Registry

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.

Vault Identity answers the question "who is this client?" The Agent Registry answers the question "is this client an approved agent, and what governance constraints apply to it?"

For API usage details, refer to the Agent Registry API documentation.

Relationship to Vault Identity

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 registration record that captures governance metadata and authorization constraints that are specific to agents.

The two components have distinct responsibilities:

Component	Responsibility
Vault Identity (entity + aliases)	Authentication binding, baseline policy attachment, group membership
Agent Registry (registration record)	Agent enrollment, authorization ceiling, ownership, description

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

Registration records

A registration record contains the following fields:

Field	Description
`id`	Unique identifier for the registration 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.
`creation_time`	Timestamp of when the registration was created.
`last_updated_time`	Timestamp of the most recent update to the registration.

Registration 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 (on-behalf-of) flow.

An agent's authorization ceiling cannot expand what an agent is allowed to do. In a delegated (on-behalf-of) 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 subject's baseline 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 registration 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.

OAuth credential requirement

Vault requires an Agent Registry record for clients that authenticate using OAuth resource server credentials (OAuth JWTs). An entity that has no registration record cannot use OAuth credentials to make requests. If you present an OAuth credential for an unregistered entity, Vault rejects the request.

In a delegation flow, where an agent acts on behalf of a subject, the actor entity must have a registration. In a direct (non-delegation) flow, the subject entity must have a registration.

Managing registrations

You manage Agent Registry records through the agent-registry/ path in the Vault API. The following paths are available:

Path	Operations	Description
`agent-registry/register`	Create, Update	Create a new registration, or update an existing one when you provide an `id`.
`agent-registry/registration/display-name/<name>`	Read, Update, Delete	The registration whose `display_name` matches the value you provide.
`agent-registry/registration/id/<id>`	Read, Update, Delete	The registration whose `id` matches the value you provide.
`agent-registry/registration/entity-id/<entity_id>`	Read	The registration whose `entity_id` matches the value you provide.
`agent-registry/registration/display-name`	List	Every registration `display_name` in the namespace.
`agent-registry/registration/id`	List	Every registration `id` in the namespace.

For complete request and response schemas, refer to the Agent Registry API documentation.