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.
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
{
"password": "superSecretPassword",
"token_policies": ["admin", "default"],
"token_bound_cidrs": ["127.0.0.1/32", "128.252.0.0/16"]
}
Sample request
$ 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.
GET
/auth/userpass/users/:username
Sample request
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/auth/userpass/users/mitchellh
Sample response
{
"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.
DELETE
/auth/userpass/users/:username
Parameters
username
(string: <required>)
- The username for the user.
Sample request
$ 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.
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
{
"password": "superSecretPassword2"
}
Sample request
$ 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.
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
{
"token_policies": ["policy1", "policy2"]
}
Sample request
$ 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.
LIST
/auth/userpass/users
Sample request
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/auth/userpass/users
Sample response
{
"data": {
"keys": ["mitchellh", "armon"]
}
}
Login
Login with the username and password.
POST
/auth/userpass/login/:username
Parameters
username
(string: <required>)
– The username for the user.password
(string: <required>)
- The password for the user.
Sample payload
{
"password": "superSecretPassword2"
}
Sample request
$ curl \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/userpass/login/mitchellh
Sample response
{
"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
}
}
Last updated