» 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.

Method Path Produces
POST /auth/userpass/users/:username 204 (empty body)

» Parameters

  • username (string: <required>) – The username for the user.
  • password (string: <required>) - The password for the user. Only required when creating the user.
  • policies (string: "") – Comma-separated list of policies. If set to empty string, only the default policy will be applicable to the user.
  • ttl (string: "") - The lease duration which decides login expiration.
  • max_ttl (string: "") - Maximum duration after which login should expire.

» Sample Payload

{
  "password": "superSecretPassword",
  "policies": "admin,default"
}

» Sample Request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    https://vault.rocks/v1/auth/userpass/users/mitchellh

» Read User

Reads the properties of an existing username.

Method Path Produces
GET /auth/userpass/users/:username 200 application/json

» Sample Request

$ curl \
    --header "X-Vault-Token: ..." \
    https://vault.rocks/v1/auth/userpass/users/mitchellh

» Sample Response

{
  "request_id": "812229d7-a82e-0b20-c35b-81ce8c1b9fa6",
  "lease_id": "",
  "lease_duration": 0,
  "renewable": false,
  "data": {
    "max_ttl": 0,
    "policies": "default,dev",
    "ttl": 0
  },
  "warnings": null
}

» Delete User

This endpoint deletes the user from the method.

Method Path Produces
DELETE /auth/userpass/users/:username 204 (empty body)

» Parameters

  • username (string: <required>) - The username for the user.

» Sample Request

$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    https://vault.rocks/v1/auth/userpass/users/mitchellh

» Update Password on User

Update password for an existing user.

Method Path Produces
POST /auth/userpass/users/:username/password 204 (empty body)

» 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 \
    https://vault.rocks/v1/auth/userpass/users/mitchellh/password

» Update Policies on User

Update policies for an existing user.

Method Path Produces
POST /auth/userpass/users/:username/policies 204 (empty body)

» Parameters

  • username (string: <required>) – The username for the user.
  • policies (string: "") – Comma-separated list of policies. If set to empty

» Sample Payload

{
  "policies": "policy1,policy2",
}

» Sample Request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    https://vault.rocks/v1/auth/userpass/users/mitchellh/policies

» List Users

List available userpass users.

Method Path Produces
LIST /auth/userpass/users 200 application/json

» Sample Request

$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST
    https://vault.rocks/v1/auth/userpass/users

» Sample Response

{
  "data": {
    "keys": [
      "mitchellh",
      "armon"
    ]
  }
}

» Login

Login with the username and password.

Method Path Produces
POST /auth/userpass/login/:username 200 application/json

» 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 \
    https://vault.rocks/v1/auth/userpass/login/mitchellh

» Sample Response

{
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": null,
  "warnings": null,
  "auth": {
    "client_token": "64d2a8f2-2a2f-5688-102b-e6088b76e344",
    "accessor": "18bb8f89-826a-56ee-c65b-1736dc5ea27d",
    "policies": ["default"],
    "metadata": {
      "username": "mitchellh"
    },
    "lease_duration": 7200,
    "renewable": true
  }
}