1---
2layout: "api"
3page_title: "Userpass - Auth Methods - HTTP API"
4sidebar_title: "Username & Password"
5sidebar_current: "api-http-auth-userpass"
6description: |-
7  This is the API documentation for the Vault username and password
8  auth method.
9---
10
11# Userpass Auth Method (HTTP API)
12
13This is the API documentation for the Vault Username & Password auth method. For
14general information about the usage and operation of the Username and Password method, please
15see the [Vault Userpass method documentation](/docs/auth/userpass.html).
16
17This documentation assumes the Username & Password method is mounted at the `/auth/userpass`
18path in Vault. Since it is possible to enable auth methods at any location,
19please update your API calls accordingly.
20
21## Create/Update User
22
23Create a new user or update an existing user. This path honors the distinction between the `create` and `update` capabilities inside ACL policies.
24
25| Method   | Path                         |
26| :--------------------------- | :--------------------- |
27| `POST`    | `/auth/userpass/users/:username`   |
28
29### Parameters
30
31- `username` `(string: <required>)` – The username for the user.
32- `password` `(string: <required>)` - The password for the user. Only required
33  when creating the user.
34- `policies` `(string: "")` – Comma-separated list of policies. If set to empty
35  string, only the `default` policy will be applicable to the user.
36- `ttl` `(string: "")` - The lease duration which decides login expiration.
37- `max_ttl` `(string: "")` - Maximum duration after which login should expire.
38- `bound_cidrs` `(string: "", or list: [])` – If set, restricts usage of the
39  login and token to client IPs falling within the range of the specified
40  CIDR(s).
41
42### Sample Payload
43
44```json
45{
46  "password": "superSecretPassword",
47  "policies": "admin,default",
48  "bound_cidrs": ["127.0.0.1/32", "128.252.0.0/16"]
49}
50```
51
52### Sample Request
53
54```
55$ curl \
56    --header "X-Vault-Token: ..." \
57    --request POST \
58    --data @payload.json \
59    http://127.0.0.1:8200/v1/auth/userpass/users/mitchellh
60```
61
62## Read User
63
64Reads the properties of an existing username.
65
66| Method   | Path                         |
67| :--------------------------- | :--------------------- |
68| `GET`    | `/auth/userpass/users/:username`   |
69
70### Sample Request
71
72```
73$ curl \
74    --header "X-Vault-Token: ..." \
75    http://127.0.0.1:8200/v1/auth/userpass/users/mitchellh
76```
77
78### Sample Response
79
80```json
81{
82  "request_id": "812229d7-a82e-0b20-c35b-81ce8c1b9fa6",
83  "lease_id": "",
84  "lease_duration": 0,
85  "renewable": false,
86  "data": {
87    "max_ttl": 0,
88    "policies": ["default", "dev"],
89    "ttl": 0
90  },
91  "warnings": null
92}
93```
94
95## Delete User
96
97This endpoint deletes the user from the method.
98
99| Method   | Path                         |
100| :--------------------------- | :--------------------- |
101| `DELETE` | `/auth/userpass/users/:username` |
102
103### Parameters
104
105- `username` `(string: <required>)` - The username for the user.
106
107### Sample Request
108
109```
110$ curl \
111    --header "X-Vault-Token: ..." \
112    --request DELETE \
113    http://127.0.0.1:8200/v1/auth/userpass/users/mitchellh
114```
115
116## Update Password on User
117
118Update password for an existing user.
119
120| Method   | Path                         |
121| :--------------------------- | :--------------------- |
122| `POST` | `/auth/userpass/users/:username/password` |
123
124### Parameters
125
126- `username` `(string: <required>)` – The username for the user.
127- `password` `(string: <required>)` - The password for the user.
128
129### Sample Payload
130
131```json
132{
133  "password": "superSecretPassword2",
134}
135```
136
137### Sample Request
138
139```
140$ curl \
141    --header "X-Vault-Token: ..." \
142    --request POST \
143    --data @payload.json \
144    http://127.0.0.1:8200/v1/auth/userpass/users/mitchellh/password
145```
146
147## Update Policies on User
148
149Update policies for an existing user.
150
151| Method   | Path                         |
152| :--------------------------- | :--------------------- |
153| `POST` | `/auth/userpass/users/:username/policies` |
154
155### Parameters
156
157- `username` `(string: <required>)` – The username for the user.
158- `policies` `(string: "")` – Comma-separated list of policies. If set to empty
159
160### Sample Payload
161
162```json
163{
164  "policies": ["policy1", "policy2"],
165}
166```
167
168### Sample Request
169
170```
171$ curl \
172    --header "X-Vault-Token: ..." \
173    --request POST \
174    --data @payload.json \
175    http://127.0.0.1:8200/v1/auth/userpass/users/mitchellh/policies
176```
177
178## List Users
179
180List available userpass users.
181
182| Method   | Path                         |
183| :--------------------------- | :--------------------- |
184| `LIST`   | `/auth/userpass/users`          |
185
186### Sample Request
187
188```
189$ curl \
190    --header "X-Vault-Token: ..." \
191    --request LIST
192    http://127.0.0.1:8200/v1/auth/userpass/users
193```
194
195### Sample Response
196
197```json
198{
199  "data": {
200    "keys": [
201      "mitchellh",
202      "armon"
203    ]
204  }
205}
206```
207
208## Login
209
210Login with the username and password.
211
212| Method   | Path                         |
213| :--------------------------- | :--------------------- |
214| `POST` | `/auth/userpass/login/:username` |
215
216### Parameters
217
218- `username` `(string: <required>)` – The username for the user.
219- `password` `(string: <required>)` - The password for the user.
220
221### Sample Payload
222
223```json
224{
225  "password": "superSecretPassword2",
226}
227```
228
229### Sample Request
230
231```
232$ curl \
233    --request POST \
234    --data @payload.json \
235    http://127.0.0.1:8200/v1/auth/userpass/login/mitchellh
236```
237
238### Sample Response
239
240```json
241{
242  "lease_id": "",
243  "renewable": false,
244  "lease_duration": 0,
245  "data": null,
246  "warnings": null,
247  "auth": {
248    "client_token": "64d2a8f2-2a2f-5688-102b-e6088b76e344",
249    "accessor": "18bb8f89-826a-56ee-c65b-1736dc5ea27d",
250    "policies": ["default"],
251    "metadata": {
252      "username": "mitchellh"
253    },
254    "lease_duration": 7200,
255    "renewable": true
256  }
257}
258```
259