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
35<%= partial "partials/tokenfields" %>
36
37### Sample Payload
38
39```json
40{
41  "password": "superSecretPassword",
42  "policies": "admin,default",
43  "bound_cidrs": ["127.0.0.1/32", "128.252.0.0/16"]
44}
45```
46
47### Sample Request
48
49```
50$ curl \
51    --header "X-Vault-Token: ..." \
52    --request POST \
53    --data @payload.json \
54    http://127.0.0.1:8200/v1/auth/userpass/users/mitchellh
55```
56
57## Read User
58
59Reads the properties of an existing username.
60
61| Method   | Path                         |
62| :--------------------------- | :--------------------- |
63| `GET`    | `/auth/userpass/users/:username`   |
64
65### Sample Request
66
67```
68$ curl \
69    --header "X-Vault-Token: ..." \
70    http://127.0.0.1:8200/v1/auth/userpass/users/mitchellh
71```
72
73### Sample Response
74
75```json
76{
77  "request_id": "812229d7-a82e-0b20-c35b-81ce8c1b9fa6",
78  "lease_id": "",
79  "lease_duration": 0,
80  "renewable": false,
81  "data": {
82    "max_ttl": 0,
83    "policies": ["default", "dev"],
84    "ttl": 0
85  },
86  "warnings": null
87}
88```
89
90## Delete User
91
92This endpoint deletes the user from the method.
93
94| Method   | Path                         |
95| :--------------------------- | :--------------------- |
96| `DELETE` | `/auth/userpass/users/:username` |
97
98### Parameters
99
100- `username` `(string: <required>)` - The username for the user.
101
102### Sample Request
103
104```
105$ curl \
106    --header "X-Vault-Token: ..." \
107    --request DELETE \
108    http://127.0.0.1:8200/v1/auth/userpass/users/mitchellh
109```
110
111## Update Password on User
112
113Update password for an existing user.
114
115| Method   | Path                         |
116| :--------------------------- | :--------------------- |
117| `POST` | `/auth/userpass/users/:username/password` |
118
119### Parameters
120
121- `username` `(string: <required>)` – The username for the user.
122- `password` `(string: <required>)` - The password for the user.
123
124### Sample Payload
125
126```json
127{
128  "password": "superSecretPassword2",
129}
130```
131
132### Sample Request
133
134```
135$ curl \
136    --header "X-Vault-Token: ..." \
137    --request POST \
138    --data @payload.json \
139    http://127.0.0.1:8200/v1/auth/userpass/users/mitchellh/password
140```
141
142## Update Policies on User
143
144Update policies for an existing user.
145
146| Method   | Path                         |
147| :--------------------------- | :--------------------- |
148| `POST` | `/auth/userpass/users/:username/policies` |
149
150### Parameters
151
152- `username` `(string: <required>)` – The username for the user.
153- `policies` `(string: "")` – Comma-separated list of policies. If set to empty
154
155### Sample Payload
156
157```json
158{
159  "policies": ["policy1", "policy2"],
160}
161```
162
163### Sample Request
164
165```
166$ curl \
167    --header "X-Vault-Token: ..." \
168    --request POST \
169    --data @payload.json \
170    http://127.0.0.1:8200/v1/auth/userpass/users/mitchellh/policies
171```
172
173## List Users
174
175List available userpass users.
176
177| Method   | Path                         |
178| :--------------------------- | :--------------------- |
179| `LIST`   | `/auth/userpass/users`          |
180
181### Sample Request
182
183```
184$ curl \
185    --header "X-Vault-Token: ..." \
186    --request LIST
187    http://127.0.0.1:8200/v1/auth/userpass/users
188```
189
190### Sample Response
191
192```json
193{
194  "data": {
195    "keys": [
196      "mitchellh",
197      "armon"
198    ]
199  }
200}
201```
202
203## Login
204
205Login with the username and password.
206
207| Method   | Path                         |
208| :--------------------------- | :--------------------- |
209| `POST` | `/auth/userpass/login/:username` |
210
211### Parameters
212
213- `username` `(string: <required>)` – The username for the user.
214- `password` `(string: <required>)` - The password for the user.
215
216### Sample Payload
217
218```json
219{
220  "password": "superSecretPassword2",
221}
222```
223
224### Sample Request
225
226```
227$ curl \
228    --request POST \
229    --data @payload.json \
230    http://127.0.0.1:8200/v1/auth/userpass/login/mitchellh
231```
232
233### Sample Response
234
235```json
236{
237  "lease_id": "",
238  "renewable": false,
239  "lease_duration": 0,
240  "data": null,
241  "warnings": null,
242  "auth": {
243    "client_token": "64d2a8f2-2a2f-5688-102b-e6088b76e344",
244    "accessor": "18bb8f89-826a-56ee-c65b-1736dc5ea27d",
245    "policies": ["default"],
246    "metadata": {
247      "username": "mitchellh"
248    },
249    "lease_duration": 7200,
250    "renewable": true
251  }
252}
253```
254