Agent Registry

The /agent-registry endpoint registers agent identities with a set of ceiling policies that constrain the maximum permissions available to the agent. An entity must have an Agent Registry record before it can authenticate using OAuth credentials.

Once you create an Agent Registry record using the /agent-registry/register endpoint, you can reference it for read, update, and delete operations in two ways:

• By the unique id of the Agent Registry record.
• By the display_name field of the record, which must be unique across all Agent Registry records in the namespace.

To list every existing record in the namespace, use one of two endpoints:

• LIST /agent-registry/registration/id returns the id of every record.
• LIST /agent-registry/registration/display-name returns the display_name of every record.

You can use the results of either LIST endpoint to address subsequent requests to specific records.

Register an agent

Create or update an Agent Registry record. When you provide an id, Vault updates the matching record; otherwise, Vault creates a new record and generates a unique id for it.

Parameters

• id (string: "") – ID of an existing registration. When set, updates the corresponding registration. When unset, creates a new Agent Registry record.

• display_name (string: <required>) – Human-readable name of the registration. The name must be unique within the target namespace for the request.

• entity_id (string: <required>) – Entity ID representing the agent. The entity must already exist in the identity store. Each entity can have only one Agent Registry record per namespace.

• description (string: "") – Human-readable description of the registration.

• owner (string: "") – Owner of the registration.

• ceiling_policies (list of strings: []) – List of policy names applied as ceiling policies to the Agent Registry record. The policies define the maximum permissions available to the agent. Cannot contain root.

• no_default_ceiling_policy (bool: false) – When set to true, opts out of automatically adding the default and default-ceiling policies to the Agent Registry record.

Sample payload

{
  "display_name": "my-agent",
  "entity_id": "fe2a8568-91cc-7580-40a4-6bed9a5867fa",
  "description": "Production deployment agent",
  "owner": "platform-team",
  "ceiling_policies": ["agent-deploy", "agent-secrets-read"]
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/agent-registry/register

Sample response

{
  "data": {
    "id": "a3b04076-e7d9-251f-4a7d-8c4f0a7b59c6",
    "display_name": "my-agent"
  }
}

Read registration by ID

Read the Agent Registry record whose id matches the value you provide.

Parameters

• id (string: <required>) – Identifier of the registration.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/agent-registry/registration/id/a3b04076-e7d9-251f-4a7d-8c4f0a7b59c6

Sample response

{
  "data": {
    "id": "a3b04076-e7d9-251f-4a7d-8c4f0a7b59c6",
    "display_name": "my-agent",
    "entity_id": "fe2a8568-91cc-7580-40a4-6bed9a5867fa",
    "description": "Production deployment agent",
    "owner": "platform-team",
    "ceiling_policies": ["agent-deploy", "agent-secrets-read", "default", "default-ceiling"],
    "no_default_ceiling_policy": false,
    "creation_time": "2026-05-15T10:30:00Z",
    "last_updated_time": "2026-05-15T10:30:00Z"
  }
}

Update registration by ID

Update the Agent Registry record whose id matches the value you provide.

Parameters

• id (string: <required>) – Identifier of the registration to update.

• display_name (string: <required>) – Human-readable name of the registration.

• entity_id (string: <required>) – Entity ID representing this agent.

• description (string: "") – Human-readable description of the registration.

• owner (string: "") – Owner of the registration.

• ceiling_policies (list of strings: []) – List of policy names applied as ceiling policies to this Agent Registry record. Cannot contain root.

• no_default_ceiling_policy (bool: false) – When set to true, opts out of automatically adding default ceiling policies.

Sample payload

{
  "display_name": "my-agent-renamed",
  "entity_id": "fe2a8568-91cc-7580-40a4-6bed9a5867fa",
  "description": "Updated production deployment agent",
  "owner": "platform-team",
  "ceiling_policies": ["agent-deploy", "agent-secrets-read", "agent-kv-read"]
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/agent-registry/registration/id/a3b04076-e7d9-251f-4a7d-8c4f0a7b59c6

Sample response

{
  "data": {
    "id": "a3b04076-e7d9-251f-4a7d-8c4f0a7b59c6",
    "display_name": "my-agent-renamed"
  }
}

Delete registration by ID

Delete the Agent Registry record whose id matches the value you provide.

Parameters

• id (string: <required>) – Identifier of the registration to delete.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/agent-registry/registration/id/a3b04076-e7d9-251f-4a7d-8c4f0a7b59c6

List registrations by ID

List the Agent Registry records in the namespace, keyed by each record's id.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/agent-registry/registration/id

Sample response

{
  "data": {
    "keys": [
      "a3b04076-e7d9-251f-4a7d-8c4f0a7b59c6",
      "b7c19832-44ad-6fa1-9e23-1a5d0c8e47b3"
    ],
    "key_info": {
      "a3b04076-e7d9-251f-4a7d-8c4f0a7b59c6": {
        "display_name": "my-agent"
      },
      "b7c19832-44ad-6fa1-9e23-1a5d0c8e47b3": {
        "display_name": "other-agent"
      }
    }
  }
}

Read registration by name

Read the Agent Registry record whose display_name matches the value you provide.

Parameters

• display_name (string: <required>) – Display name of the registration.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/agent-registry/registration/display-name/my-agent

Sample response

{
  "data": {
    "id": "a3b04076-e7d9-251f-4a7d-8c4f0a7b59c6",
    "display_name": "my-agent",
    "entity_id": "fe2a8568-91cc-7580-40a4-6bed9a5867fa",
    "description": "Production deployment agent",
    "owner": "platform-team",
    "ceiling_policies": ["agent-deploy", "agent-secrets-read", "default", "default-ceiling"],
    "no_default_ceiling_policy": false,
    "creation_time": "2026-05-15T10:30:00Z",
    "last_updated_time": "2026-05-15T10:30:00Z"
  }
}

Update registration by name

Update the Agent Registry record whose display_name matches the value you provide.

Parameters

• display_name (string: <required>) – Display name of the registration to update.

• entity_id (string: <required>) – Entity ID representing this agent.

• description (string: "") – Human-readable description of the registration.

• owner (string: "") – Owner of the registration.

• ceiling_policies (list of strings: []) – Ceiling policies applied to this Agent Registry record. Cannot contain root.

• no_default_ceiling_policy (bool: false) – When set to true, opts out of automatically adding default ceiling policies.

Sample payload

{
  "entity_id": "fe2a8568-91cc-7580-40a4-6bed9a5867fa",
  "description": "Updated via display name",
  "owner": "platform-team",
  "ceiling_policies": ["agent-deploy", "agent-secrets-read"]
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/agent-registry/registration/display-name/my-agent

Sample response

{
  "data": {
    "id": "a3b04076-e7d9-251f-4a7d-8c4f0a7b59c6",
    "display_name": "my-agent"
  }
}

Delete registration by name

Delete the Agent Registry record whose display_name matches the value you provide.

Parameters

• display_name (string: <required>) – Display name of the registration to delete.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/agent-registry/registration/display-name/my-agent

List registrations by name

List the Agent Registry records in the namespace, keyed by each record's display_name.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/agent-registry/registration/display-name

Sample response

{
  "data": {
    "keys": [
      "my-agent",
      "other-agent"
    ],
    "key_info": {
      "my-agent": {
        "display_name": "my-agent"
      },
      "other-agent": {
        "display_name": "other-agent"
      }
    }
  }
}

Read registration by entity ID

Read the Agent Registry record whose entity_id matches the value you provide.

Parameters

• entity_id (string: <required>) – Entity ID to look up.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/agent-registry/registration/entity-id/fe2a8568-91cc-7580-40a4-6bed9a5867fa

Sample response

{
  "data": {
    "id": "a3b04076-e7d9-251f-4a7d-8c4f0a7b59c6",
    "display_name": "my-agent",
    "entity_id": "fe2a8568-91cc-7580-40a4-6bed9a5867fa",
    "description": "Production deployment agent",
    "owner": "platform-team",
    "ceiling_policies": ["agent-deploy", "agent-secrets-read", "default", "default-ceiling"],
    "no_default_ceiling_policy": false,
    "creation_time": "2026-05-15T10:30:00Z",
    "last_updated_time": "2026-05-15T10:30:00Z"
  }
}