/sys/policies/password/

The /sys/policies/password/ endpoints are used to manage password generation policies in Vault. Not all secret engines utilize password policies, so check the documentation for the engine you are using for compatibility.

~> Password policies are only available in Vault version 1.5+.

See Password Policies for details of how password policies work as well as the syntax of the policies themselves.

Create/Update password policy

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

Prior to Vault saving the password policy, it will attempt to generate a number of passwords from the policy. This helps prevent creating password policies that are impossible to satisfy as well as prevent password policies that are overly restrictive which prevents both a poor security posture for the policy as well as preventing performance problems due to slow generation times.

Method	Path
POST	/sys/policies/password/:name

Parameters

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

• policy (string: <required>) - Specifies the password policy document. This can be base64-encoded to avoid string escaping. See Password Policy Syntax for details on password policy definitions.

Sample payload

{
  "policy": "length = 20\nrule \"charset\" { ..."
}

Sample request

cURL:

$ cat payload.json
{
  "policy": "length = 20\nrule \"charset\" {\n  charset = \"abcde\"\n}\n"
}

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

Vault CLI:

$ cat my-policy.hcl
length = 20
rule "charset" {
    charset = "abcde"
}

$ vault write sys/policies/password/my-policy policy=@my-policy.hcl

List password policies

This endpoints list the password policies.

Method	Path
LIST	/sys/policies/password
GET	/sys/policies/password?list=true

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/sys/policies/password

Sample response

{
  "request_id": "58e2540f-8c51-6390-46de-38e279e75468",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "keys": [
      "my-policy"
    ]
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null
}

Read password policy

This endpoint retrieves information about the named password policy.

Method	Path
GET	/sys/policies/password/:name

Parameters

• name (string: <required>) – Specifies the name of the password 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/policies/password/my-policy

Sample response

{
  "policy": "length = 20\nrule \"charset\" { ..."
}

Delete password policy

This endpoint deletes the password policy with the given name. This does not check if any secret engines are using it prior to deletion, so you should ensure that any engines that are utilizing this password policy are changed to a different policy (or to that engines' default behavior).

Method	Path
DELETE	/sys/policies/password/:name

Parameters

• name (string: <required>) – Specifies the name of the password 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/policies/password/my-policy

Generate password from password policy

This endpoint generates a password from the specified existing password policy.

Method	Path
GET	/sys/policies/password/:name/generate

Parameters

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

Sample request

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

Sample response

{
  "password": "..."
}