Skip to main content

/sys/policy

The /sys/policy endpoint is used to manage ACL policies in OpenBao.

List policies​

This endpoint lists all configured policies. This endpoint optionally takes a prefix to list policies under.

MethodPath
GET/sys/policy
LIST/sys/policy/:prefix

Sample request​

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/sys/policy

Sample response​

{
  "policies": ["root", "deploy"]
}

Read policy​

This endpoint retrieve the policy body for the named policy.

MethodPath
GET/sys/policy/:name

Parameters​

  • name (string: <required>) – Specifies the name of the policy to retrieve. This is specified as part of the request URL.

Sample request​

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/sys/policy/my-policy

Sample response​

{
  "name": "my-policy",
  "rules": "path \"secret/*\"...",
  "modified": "2025-03-25T16:50:49.348095648-05:00",
  "version": "1",
  "cas_required": false
}

Create/Update policy​

This endpoint adds a new or updates an existing policy. Once a policy is updated, it takes effect immediately to all associated users.

MethodPath
POST/sys/policy/:name

Parameters​

  • name (string: <required>) – Specifies the name of the policy to create. This is specified as part of the request URL.

  • policy (string: <required>) - Specifies the policy document.

  • expiration (time: <optional>) - Specifies an expiration time after which the policy will no longer be valid and will be removed on next load. Cannot be set in conjunction with ttl and cannot be in the past.

  • ttl (duration: <optional>) - Specifies a time for which the policy will be valid and will be removed on next load. Cannot be set in conjunction with expiration.

  • cas (int: <optional>) - Optional version of the policy to compare against before performing any modifications (check-and-set). If the existing version of the policy has cas_required=true or the cas_required=true parameter is provided on the request, the cas parameter is required. When no policy exists and this should strictly be a create operation, set the value to -1; existing policies created before this field start at version 0.

  • cas_required (bool: <optional>) - Whether or not check-and-set semantics should be required on this and the next request. Note that because this is a create/update operation, this parameter needs to reset to true on every subsequent operation for continued usage. When set to true, cas becomes a required parameter. Defaults to false.

Sample payload​

{
  "policy": "path \"secret/foo\" {..."
}

Sample request​

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/sys/policy/my-policy

Delete policy​

This endpoint deletes the policy with the given name. This will immediately affect all users associated with this policy.

MethodPath
DELETE/sys/policy/:name

Parameters​

  • name (string: <required>) – Specifies the name of the policy to delete. This is specified as part of the request URL.

Sample request​

$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/sys/policy/my-policy