# Userpass auth method (HTTP API)

This is the API documentation for the Vault Username & Password auth method. For general information about the usage and operation of the Username and Password method, please see the Vault Userpass method documentation.

This documentation assumes the Username & Password method is mounted at the `/auth/userpass` path in Vault. Since it is possible to enable auth methods at any location, please update your API calls accordingly.

### Create/Update user

Create a new user or update an existing user. This path honors the distinction between the `create` and `update` capabilities inside ACL policies.

| Method | Path                             |
| ------ | -------------------------------- |
| `POST` | `/auth/userpass/users/:username` |

#### Parameters

* `username` `(string: <required>)` – The username for the user. Accepted characters: alphanumeric plus "\_", "-", "." (underscore, hyphen and period); username cannot begin with a hyphen, nor can it begin or end with a period.
* `password` `(string: <required>)` - The password for the user. Only required when creating the user.

@include 'tokenfields.mdx'

#### Sample payload

```json
{
  "password": "superSecretPassword",
  "token_policies": ["admin", "default"],
  "token_bound_cidrs": ["127.0.0.1/32", "128.252.0.0/16"]
}
```

#### Sample request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/auth/userpass/users/mitchellh
```

### Read user

Reads the properties of an existing username.

| Method | Path                             |
| ------ | -------------------------------- |
| `GET`  | `/auth/userpass/users/:username` |

#### Sample request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/auth/userpass/users/mitchellh
```

#### Sample response

```json
{
  "request_id": "0ad1be52-9398-4b3c-f58b-98e427406471",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "token_bound_cidrs": [
      "127.0.0.1",
      "128.252.0.0/16"
    ],
    "token_explicit_max_ttl": 0,
    "token_max_ttl": 0,
    "token_no_default_policy": false,
    "token_num_uses": 0,
    "token_period": 0,
    "token_policies": [
      "admin",
      "default"
    ],
    "token_ttl": 0,
    "token_type": "default"
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null
}
```

### Delete user

This endpoint deletes the user from the method.

| Method   | Path                             |
| -------- | -------------------------------- |
| `DELETE` | `/auth/userpass/users/:username` |

#### Parameters

* `username` `(string: <required>)` - The username for the user.

#### Sample request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/auth/userpass/users/mitchellh
```

### Update password on user

Update password for an existing user.

| Method | Path                                      |
| ------ | ----------------------------------------- |
| `POST` | `/auth/userpass/users/:username/password` |

#### Parameters

* `username` `(string: <required>)` – The username for the user.
* `password` `(string: <required>)` - The password for the user.

#### Sample payload

```json
{
  "password": "superSecretPassword2"
}
```

#### Sample request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/auth/userpass/users/mitchellh/password
```

### Update policies on user

Update policies for an existing user.

| Method | Path                                      |
| ------ | ----------------------------------------- |
| `POST` | `/auth/userpass/users/:username/policies` |

#### Parameters

* `username` `(string: <required>)` – The username for the user.
* `token_policies` `(array: [] or comma-delimited string: "")` - List of policies to encode onto generated tokens. Depending on the auth method, this list may be supplemented by user/group/other values.

#### Sample payload

```json
{
  "token_policies": ["policy1", "policy2"]
}
```

#### Sample request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/auth/userpass/users/mitchellh/policies
```

### List users

List available userpass users.

| Method | Path                   |
| ------ | ---------------------- |
| `LIST` | `/auth/userpass/users` |

#### Sample request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/auth/userpass/users
```

#### Sample response

```json
{
  "data": {
    "keys": ["mitchellh", "armon"]
  }
}
```

### Login

Login with the username and password.

| Method | Path                             |
| ------ | -------------------------------- |
| `POST` | `/auth/userpass/login/:username` |

#### Parameters

* `username` `(string: <required>)` – The username for the user.
* `password` `(string: <required>)` - The password for the user.

#### Sample payload

```json
{
  "password": "superSecretPassword2"
}
```

#### Sample request

```shell-session
$ curl \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/auth/userpass/login/mitchellh
```

#### Sample response

```json
{
  "request_id": "ae1882ba-f60a-7629-ce1a-6618c482de3e",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": null,
  "wrap_info": null,
  "warnings": null,
  "auth": {
    "client_token": "hvs.CAESIJyeFmhLYRWVXPJStT3fDP1ZdFkon_otuk1sJUpkfk_WGh4KHGh2cy5xdW9XVHBnVUwwbzB1ZEhzZkpkRmVoU08",
    "accessor": "iP2Lw1JXpjlALbgJSeIx51n7",
    "policies": [
      "default",
      "policy1",
      "policy2"
    ],
    "token_policies": [
      "default",
      "policy1",
      "policy2"
    ],
    "metadata": {
      "username": "mitchellh"
    },
    "lease_duration": 2764800,
    "renewable": true,
    "entity_id": "0660dce5-4f2c-926a-8b15-158901557d9d",
    "token_type": "service",
    "orphan": true,
    "mfa_requirement": null,
    "num_uses": 0
  }
}
```