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