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