HashiCorp Vault User Management API Guide

Auth method: Vault Token (X-Vault-Token header); tokens obtained via login endpoints for each auth method (userpass, LDAP, OIDC, etc.)

Setup steps

1. Enable an auth method: POST /v1/sys/auth/ with type (e.g., 'userpass')
2. Obtain a Vault token by calling the auth method's login endpoint (e.g., POST /v1/auth/userpass/login/)
3. Include the returned client_token in subsequent requests as the X-Vault-Token header
4. For automated/service use, create a token with appropriate policies via POST /v1/auth/token/create
5. Assign policies to tokens or entities to control access to user-management paths

Required scopes

Create or update userpass user

• Method: POST
• URL: /v1/auth/userpass/users/{username}
• Watch out for: Returns 204 on success with no body. Same endpoint is used for both create and update.

Request example

POST /v1/auth/userpass/users/alice
X-Vault-Token: <token>
{
  "password": "s3cr3t",
  "policies": "default,dev-policy",
  "token_ttl": "1h"
}

Response example

HTTP 204 No Content

Read userpass user

• Method: GET
• URL: /v1/auth/userpass/users/{username}
• Watch out for: Password is never returned in the response.

Request example

GET /v1/auth/userpass/users/alice
X-Vault-Token: <token>

Response example

{
  "data": {
    "policies": ["default","dev-policy"],
    "token_ttl": 3600,
    "token_max_ttl": 0
  }
}

List userpass users

• Method: GET
• URL: /v1/auth/userpass/users?list=true
• Watch out for: Use the LIST HTTP method or append ?list=true. Returns only usernames, not full user objects.

Request example

LIST /v1/auth/userpass/users
X-Vault-Token: <token>

Response example

{
  "data": {
    "keys": ["alice", "bob", "carol"]
  }
}

Delete userpass user

• Method: DELETE
• URL: /v1/auth/userpass/users/{username}
• Watch out for: Does not automatically revoke existing tokens issued to that user.

Request example

DELETE /v1/auth/userpass/users/alice
X-Vault-Token: <token>

Response example

HTTP 204 No Content

Update userpass password

• Method: POST
• URL: /v1/auth/userpass/update-password/{username}
• Watch out for: Users can call this endpoint against their own username with a valid token; admins can call it for any user.

Request example

POST /v1/auth/userpass/update-password/alice
X-Vault-Token: <token>
{
  "password": "newP@ssw0rd"
}

Response example

HTTP 204 No Content

Create Identity entity

• Method: POST
• URL: /v1/identity/entity
• Watch out for: Entity name must be unique within the namespace. Entities are separate from auth method users and must be linked via entity-alias.

Request example

POST /v1/identity/entity
X-Vault-Token: <token>
{
  "name": "alice",
  "metadata": {"department": "engineering"},
  "policies": ["dev-policy"]
}

Response example

{
  "data": {
    "id": "7d2e3179-f69b-450c-7179-ac8ee8bd8ca9",
    "name": "alice"
  }
}

List Identity entities

• Method: GET
• URL: /v1/identity/entity/name?list=true
• Watch out for: Can also list by ID via /v1/identity/entity/id?list=true. Returns names/IDs only, not full objects.

Request example

LIST /v1/identity/entity/name
X-Vault-Token: <token>

Response example

{
  "data": {
    "keys": ["alice", "bob"]
  }
}

Disable/enable Identity entity

• Method: POST
• URL: /v1/identity/entity/id/{id}
• Watch out for: Disabling an entity blocks all logins for that entity across all linked auth method aliases, but does not revoke existing tokens.

Request example

POST /v1/identity/entity/id/7d2e3179-...
X-Vault-Token: <token>
{
  "disabled": true
}

Response example

{
  "data": {
    "id": "7d2e3179-...",
    "disabled": true
  }
}

• Rate limits: Vault does not impose built-in HTTP rate limits by default. Rate limiting can be configured via the 'request_limiter' stanza (Vault Enterprise 1.16+) or via a reverse proxy in front of Vault.
• Rate-limit headers: No
• Retry-After header: No
• Rate-limit notes: HCP Vault may enforce cluster-level throughput limits. Self-managed Vault relies on operator-configured limits or upstream proxy rate limiting.
• Pagination method: token
• Default page size: 0
• Max page size: 0
• Pagination pointer: list=true (LIST HTTP method or ?list=true query param returns all keys; no page size param - full key list is returned)

• Webhooks available: No
• Webhook notes: Vault does not provide native outbound webhooks for user-management events.
• Alternative event strategy: Use Vault Audit Devices (file, syslog, socket) to stream all API request/response logs. Audit log entries can be forwarded to a SIEM or event pipeline (e.g., Splunk, Elastic) to trigger downstream actions on user events.

• SCIM available: No
• SCIM version: Not documented
• Plan required: Enterprise
• Endpoint: Not documented

Limitations:

• Vault does not implement a SCIM 2.0 endpoint natively in any edition.
• User provisioning is handled via auth method APIs (userpass, LDAP, OIDC) or Identity engine APIs.
• Enterprise SAML auth method (v1.15.0+) supports IdP-driven SSO but not SCIM provisioning.
• Automated provisioning workflows must use the Vault HTTP API or Terraform provider (hashicorp/vault).

Three workflows cover the majority of programmatic user management needs:

• Provision a developer: Enable userpass (POST /v1/sys/auth/userpass), create the user with a policy and TTL (POST /v1/auth/userpass/users/{username}), then optionally build the identity graph by creating an entity and linking the alias. Retrieve the mount accessor from GET /v1/sys/auth - it is required for alias creation and is not guessable.

• Offboard a user: Look up the entity ID via GET /v1/identity/entity/name/{name}, set disabled: true via POST /v1/identity/entity/id/{id} to block new logins across all linked auth methods, then explicitly revoke each active token by accessor via POST /v1/auth/token/revoke-accessor. Disabling the entity alone does not terminate existing sessions.

• Bulk audit: LIST /v1/auth/userpass/users returns usernames only. Fetching full policy and TTL details requires a separate GET per user - there is no batch read endpoint. For large deployments this is an N+1 request pattern; design your audit pipeline accordingly.

Provision a new developer user with scoped access

1. Ensure userpass auth method is enabled: POST /v1/sys/auth/userpass {"type":"userpass"}
2. Create the user with a policy: POST /v1/auth/userpass/users/alice {"password":"...","policies":"dev-policy","token_ttl":"8h"}
3. Optionally create an Identity entity for richer metadata: POST /v1/identity/entity {"name":"alice","metadata":{"team":"backend"}}
4. Link the userpass alias to the entity: POST /v1/identity/entity-alias {"name":"alice","canonical_id":"","mount_accessor":""}
5. Verify by reading the user: GET /v1/auth/userpass/users/alice

Watch out for: The mount accessor for the userpass mount is required when creating entity-aliases. Retrieve it via GET /v1/sys/auth and find the accessor field for the userpass mount.

Disable a user across all auth methods (offboarding)

1. Look up the user's Identity entity ID: GET /v1/identity/entity/name/alice
2. Disable the entity to block all future logins: POST /v1/identity/entity/id/ {"disabled":true}
3. List and revoke all active tokens for the entity using the accessor: POST /v1/auth/token/revoke-accessor {"accessor":""}
4. Optionally delete the userpass user: DELETE /v1/auth/userpass/users/alice
5. Confirm no active tokens remain by checking audit logs or token lookup

Watch out for: Disabling the entity blocks new logins but does not invalidate existing tokens. Explicit token revocation is required for immediate access termination.

Bulk list and audit all userpass users

1. List all usernames: LIST /v1/auth/userpass/users (returns keys array)
2. Iterate over each username and fetch details: GET /v1/auth/userpass/users/
3. Cross-reference with Identity entities: LIST /v1/identity/entity/name to find entities without linked aliases
4. Check token policies and TTLs in each user's data response for compliance review

Watch out for: The LIST endpoint returns only usernames, not full objects. A separate GET per user is required to retrieve policies and token settings. For large user counts, this is N+1 requests with no batch endpoint available.

The most dangerous assumption is that deleting a userpass user revokes their access. It does not. DELETE /v1/auth/userpass/users/{username} removes the credential record but leaves all previously issued tokens valid until their TTL expires or they are explicitly revoked.

Immediate access termination requires a separate token revocation step using the accessor.

A second common trap: the list capability is distinct from read in Vault policy. A token with only read on auth/userpass/users/* cannot enumerate users. List operations require an explicit list capability grant on the path, and omitting it produces a 403 with no descriptive error about the missing capability.

For Enterprise deployments using namespaces, all API paths are namespace-scoped. Omitting the X-Vault-Namespace header when targeting a non-root namespace will silently operate against the root namespace, potentially creating or reading resources in the wrong scope. Vault does not return a warning - the request succeeds against the wrong target.

Rate limiting is not built into Vault OSS; configure the request_limiter stanza (Enterprise 1.16+) or place a rate-limiting proxy upstream before exposing the API to automated workflows.