Skip to content

API Access#

The Vault HTTP API gives you full access to Vault using REST like HTTP verbs. Every aspect of Vault can be controlled using the APIs. The Vault CLI uses the HTTP API to access Vault similar to all other consumers. For more information, visit Hashicorp's API Developer Documentation

A quick way to get started and view/try out Vault API endpoints is to login to the Vault GUI, navigate to your namespace and choose Tools > API Explorer.

Note

All examples use the X-Vault-Namespace: admin/<your-namespace> header. You can also omit this header and put the namespace in the URL directly following the /v1/ portion i.e. /v1/admin/<your-namespace>/

Authorization#

In order to use the Vault API, a vault token or other authentication is required for most requests.

Token - SAML#

The Vault API does not directly support SAML authentication. If an individual wants to use their own permissions to access vault, they will first need to login via the GUI or CLI and obtain a vault token (good for 60 minutes) to utilize the API.

Obtaining token via CLI#

You will need the vault enterprise binary installed to use the cli. See the cli article

Text Only
vault login --method=saml --namepsace=admin

The first key/value shown after logging in will be your token (starts with hvs). Otherwise, you can retrieve your current token with this command (id value):

Text Only
vault token lookup

Obtaining token via GUI#

  1. Login to the Vault GUI

  2. Navigate to the upper left corner and look for the person icon > Copy token

Vault GUI Namespace

Approle#

For unattended machine access to the api, a good option for authentication would be an approle. Here are some example requests to setup an approle via the API.

Text Only
# Create policy to give the approle access to read and list all secrets at secret/* (example only, configure the appropriate access)
curl --header "X-Vault-Token: <your-saml-token>" \
     --header "X-Vault-Namespace: admin/<your-namespace>" \
     --request PUT \
     --data '{"policy":"path \"secret/*\" { capabilities = [\"read\", \"list\"] }"}' \
     https://hcp-vault-public-vault-fc507e0d.5d5b1f21.z1.hashicorp.cloud:8200/v1/sys/policies/acl/test_approle_policy

# Create the approle
curl --header "X-Vault-Token: <your-saml-token>" \
     --header "X-Vault-Namespace: admin/<your-namespace>" \
     --request POST \
     --data '{"policies": ["test_approle_policy", "default"]}' \
    https://hcp-vault-public-vault-fc507e0d.5d5b1f21.z1.hashicorp.cloud:8200/v1/auth/approle/role/test_approle_role

# Retrieve the Role ID (data.role-id)
curl --header "X-Vault-Token: <your-saml-token>" \
     --header "X-Vault-Namespace: admin/<your-namespace>" \
     --request GET \
    https://hcp-vault-public-vault-fc507e0d.5d5b1f21.z1.hashicorp.cloud:8200/v1/auth/approle/role/test_approle_role/role-id

# Generate the Secret ID (data.secret-id)
curl --header "X-Vault-Token: <your-saml-token>" \
     --header "X-Vault-Namespace: admin/<your-namespace>" \
     --request POST \
    https://hcp-vault-public-vault-fc507e0d.5d5b1f21.z1.hashicorp.cloud:8200/v1/auth/approle/role/test_approle_role/secret-id

Examples#

Example API usage

Note

Some scripting and programming languages have vault packages or modules that directly support Vault that may be easier to utilize than the API directly. See our UMN integration examples documentation or Hashicorp's Developer quick start guide

Generate a token with your approle to utilize in subsequent api requests#

Text Only
# auth.client_token response (token starts with hvs)
curl --header "X-Vault-Namespace: admin/<your-namespace>" \
     --request POST \
     --data '{"role_id":"<your-role-id>","secret_id":"<your-secret-id>"}' \
     https://hcp-vault-public-vault-fc507e0d.5d5b1f21.z1.hashicorp.cloud:8200/v1/auth/approle/login

Retrieve Secret#

Text Only
curl --header "X-Vault-Token: <your-token>" \
     --header "X-Vault-Namespace: admin/<your-namespace>" \
     --request GET \
    https://hcp-vault-public-vault-fc507e0d.5d5b1f21.z1.hashicorp.cloud:8200/v1/secret/data/example

Create/Overwrite Secret#

Text Only
curl --header "X-Vault-Token: <your-token>" \
     --header "X-Vault-Namespace: admin/<your-namespace>" \
     --request POST \
     --data '{"data": {"foo": "bar"}}' \
     https://hcp-vault-public-vault-fc507e0d.5d5b1f21.z1.hashicorp.cloud:8200/v1/secret/data/example