Vault
HomeDocumentationTutorialsTry Cloud!
  • Vault
  • Documentation
    • What is Vault?
    • Use Cases
    • Setup
      • Install
      • Configuration
    • Get Started
      • Starting the server
      • Your first secret
      • Deploying Vault on VMs with Let's encrypt! TLS certs
    • Concepts
      • Operations
        • Seal/Unseal
        • "Dev" server mode
        • Namespace lock and unlock
        • Lease, renew, and revoke
        • Lease Explosions
        • Mount migration
        • Client count
        • Resource quotas
        • Response wrapping
      • Authentication
        • Identity
        • Tokens
        • OIDC provider
        • Username templating
        • Passwordless
      • Secrets
      • Storage
        • Integrated storage
        • High availability mode (HA)
        • Recovery mode
      • Policies
  • Tutorials
    • CLI
      • Operations
        • Deploy Vault
        • Using the HTTP API
        • Unseal/Seal
      • Authentication
        • Token
        • GitHub authentication
        • Username/Password
        • TLS Client Certificates
        • SSH Keys
        • AWS, Azure, GCP and external auth methods
          • Azure
          • AWS
          • GCP
          • Github
          • Terraform
      • Secrets
        • Secrets engines
        • Built-in help
      • Access Control
        • Policies
    • UI
      • Authentication
        • Username/Password
        • Passwordless
      • Operations
        • Unseal / Seal
        • API Explorer
      • Secrets
        • Secrets engines
      • Access Control
        • Policies
    • Use Cases
      • Namespaces
      • MongoDB admin password
      • VM Disk Encryption Keys
      • VM SSH Keys
      • Kubernetes Configuration
      • GitHub Actions
      • Dynamic credentials for cloud providers
        • AWS
        • Azure
        • GCP
  • CLI
    • agent
    • audit
    • auth
    • debug
    • delete
    • events
    • kv
    • lease
    • license
    • list
    • login
    • monitor
    • namespace
    • operator
    • patch
    • path-help
    • pki
    • plugin
    • policy
    • print
    • proxy
    • read
    • secrets
    • server
    • ssh
    • status
    • token
    • transit
    • unwrap
    • version
    • version-history
    • write
  • API
    • Secrets engines
      • AliCloud secrets engine (API)
      • AWS secrets engine (API)
      • Azure secrets engine (API)
      • Cubbyhole secrets engine (API)
      • Database
        • Cassandra database plugin HTTP API
        • Elasticsearch database plugin HTTP API
        • Influxdb database plugin HTTP API
        • MongoDB database plugin HTTP API
        • MSSQL database plugin HTTP API
        • MySQL/MariaDB database plugin HTTP API
        • Oracle database plugin HTTP API
        • PostgreSQL database plugin HTTP API
        • Redis database plugin HTTP API
        • Redis ElastiCache database plugin HTTP API
        • Redshift database plugin HTTP API
        • Snowflake database plugin HTTP API
      • Google Cloud secrets engine (API)
      • Google Cloud KMS secrets engine (API)
      • Identity
        • entity
        • entity-alias
        • group
        • group-alias
        • tokens
        • lookup
        • oidc-provider
        • MFA
          • duo
          • okta
          • pingid
          • totp
          • login-enforcement
      • KV secrets engine (API)
      • Buckypaper secrets engine
      • Kubernetes secrets engine (API)
      • Nomad secrets engine (API)
      • LDAP secrets engine (API)
      • PKI secrets engine (API)
      • RabbitMQ secrets engine (API)
      • SSH secrets engine (API)
      • TOTP secrets engine (API)
      • Transit secrets engine (API)
    • Auth engines
      • AliCloud auth method (API)
      • AppRole auth method (API)
      • AWS auth method (API)
      • Azure auth method (API)
      • Pivotal Cloud Foundry (CF) auth method (API)
      • GitHub auth method (API)
      • Google Cloud auth method (API)
      • JWT/OIDC auth method (API)
      • Kerberos auth method (API)
      • Kubernetes auth method (API)
      • LDAP auth method (API)
      • OCI auth method (API)
      • Okta auth method (API)
      • Passwordless auth method (API)
      • RADIUS auth method (API)
      • TLS certificate auth method (API)
      • Token auth method (API)
      • Userpass auth method (HTTP API)
    • Service engines
      • Licence Manager
    • System backend
      • /sys/audit
      • /sys/audit-hash
      • /sys/auth
      • /sys/capabilities
      • /sys/capabilities-accessor
      • /sys/capabilities-self
      • /sys/config/auditing/request-headers
      • /sys/config/control-group
      • /sys/config/cors
      • /sys/config/reload
      • /sys/config/state
      • /sys/config/ui
      • /sys/decode-token
      • /sys/experiments
      • /sys/generate-recovery-token
      • /sys/generate-root
      • /sys/health
      • /sys/host-info
      • /sys/in-flight-req
      • /sys/init
      • /sys/internal/counters
      • /sys/internal/inspect
        • /sys/internal/inspect/router
      • /sys/internal/specs/openapi
      • /sys/internal/ui/feature-flags
      • /sys/internal/ui/mounts
      • /sys/internal/ui/namespaces
      • /sys/internal/ui/resultant-acl
      • /sys/key-status
      • /sys/ha-status
      • /sys/leader
      • /sys/leases
      • /sys/license/status
      • /sys/locked-users
      • /sys/loggers
      • /sys/metrics
      • /sys/monitor
      • /sys/mounts
      • /sys/namespaces
      • /sys/plugins/reload/backend
      • /sys/plugins/catalog
      • /sys/plugins/runtimes/catalog
      • /sys/policy
      • /sys/policies/
      • /sys/policies/password/
      • /sys/pprof
      • /sys/quotas/config
      • /sys/quotas/rate-limit
      • /sys/quotas/lease-count
      • /sys/raw
      • /sys/rekey
      • /sys/rekey-recovery-key
      • /sys/remount
      • /sys/rotate
      • /sys/rotate/config
      • /sys/seal
      • /sys/seal-status
      • /sys/seal-backend-status
      • /sys/step-down
      • /sys/storage
        • /sys/storage/raft
        • /sys/storage/raft/autopilot
      • /sys/tools
      • /sys/unseal
      • /sys/version-history
      • /sys/wrapping/lookup
      • /sys/wrapping/rewrap
      • /sys/wrapping/unwrap
      • /sys/wrapping/wrap
  • Resources
    • Blog
    • GitHub
    • Youtube
    • CCx101
Powered by GitBook
On this page
  • Create/Update user
  • Read user
  • Delete user
  • Update password on user
  • Update policies on user
  • List users
  • Login
  1. API
  2. Auth engines

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

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.

Method
Path

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.

Method
Path

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.

Method
Path

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.

Method
Path

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.

Method
Path

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.

Method
Path

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
  }
}
PreviousToken auth method (API)NextService engines

Last updated 6 months ago