open-vault/website/pages/api-docs/system/policies-password.mdx

---
layout: api
page_title: /sys/policies/password - HTTP API
sidebar_title: <code>/sys/policies/password</code>
description: >-
  The `/sys/policies/password` endpoints are used to manage password generation policies in Vault.
---

# `/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](/docs/concepts/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                           |
| :----- | :----------------------------- |
| `PUT`  | `/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](#password-policy-syntax)
  for details on password policy definitions.

### Sample Payload

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

### Sample Request
**cURL:**
```shell
$ cat payload.json
{
  "policy": "length = 20\nrule \"charset\" {\n  charset = \"abcde\"\n}\n"
}

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

**Vault CLI:**
```shell
$ cat my-policy.hcl
length = 20
rule "charset" {
    charset = "abcde"
}

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

## 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

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

### Sample Response
```json
{
  "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

```shell
$ 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

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

### Sample Response
```json
{
  "password": "..."
}
```