HTTP API | Vault | HashiCorp Developer (2023)

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 theHTTP API to access Vault similar to all other consumers.

All API routes are prefixed with /v1/.

This documentation is only for the v1 API, which is currently the only version.

Backwards compatibility: At the current version, Vault does not yetpromise backwards compatibility even with the v1 prefix. We'll remove thiswarning when this policy changes. At this point in time the core API (thatis, sys/ routes) change very infrequently, but various secrets engines/authmethods/etc. sometimes have minor changes to accommodate new features asthey're developed.

The API is expected to be accessed over a TLS connection at all times, with avalid certificate that is verified by a well-behaved client. It is possible todisable TLS verification for listeners, however, so API clients should expectto have to do both depending on user settings.

Authentication

Once Vault is unsealed, almost every other operation requires a client token.A user may have a client token sent to them. The client token must be sent aseither the X-Vault-Token HTTP Header or as Authorization HTTP Header usingthe Bearer <token> scheme.

Otherwise, a client token can be retrieved using an authenticationengine.

Each auth method has one or more unauthenticated login endpoints. Theseendpoints can be reached without any authentication, and are used forauthentication to Vault itself. These endpoints are specific to each authmethod.

Responses from auth login methods that generate an authentication token aresent back to the client in JSON. The resulting token should be saved on theclient or passed via the X-Vault-Token or Authorization header for future requests.

Several Vault APIs require specifying path parameters. The path parameter cannot endin periods. Otherwise, Vault will return a 404 unsupported path error.

Namespaces

When using Namespaces the final path of the APIrequest is relative to the X-Vault-Namespace header. For instance, if arequest URI is secret/foo with the X-Vault-Namespace header set as ns1/ns2/,then the resulting request path to Vault will be ns1/ns2/secret/foo.

Note that it is semantically equivalent to use the full path rather than theX-Vault-Namespace header, Vault will match the corresponding namespacebased on correlating user input. Similar path results may be achieved ifX-Vault-Namespace is set to ns1/ with the request path of ns2/secret/fooas well, or otherwise if X-Vault-Namespace is omitted entirely and instead acomplete path is provided such as: ns1/ns2/secret/foo.

For example, the following two commands result in equivalent requests:

$ curl \ -H "X-Vault-Token: f3b09679-3001-009d-2b80-9c306ab81aa6" \ -H "X-Vault-Namespace: ns1/ns2/" \ -X GET \ http://127.0.0.1:8200/v1/secret/foo
$ curl \ -H "X-Vault-Token: f3b09679-3001-009d-2b80-9c306ab81aa6" \ -X GET \ http://127.0.0.1:8200/v1/ns1/ns2/secret/foo

Typically the request data, body and response data to and from Vault is in JSON.Vault sets the Content-Type header appropriately with its response and doesnot require it from the clients request.

The demonstration below uses the KVv1 secrets engine, which is asimple Key/Value store. Please read the API documentation of KV secret enginesfor details of KVv1 compared to KVv2 and how they differ in their URI pathsas well as the features available in version 2 of the KV secrets engine.

For KVv1, reading a secret using the HTTP API is done by issuing a GET:

/v1/secret/foo

This maps to secret/foo where foo is the key in the secret/ mount, whichis mounted by default on a fresh Vault install and is of type kv.

Here is an example of reading a secret using cURL:

$ curl \ -H "X-Vault-Token: f3b09679-3001-009d-2b80-9c306ab81aa6" \ -X GET \ http://127.0.0.1:8200/v1/secret/foo

A few endpoints consume calls with GET query string parameters, but only ifthose parameters are not sensitive, especially since some load balancers willbe able log these. Most endpoints that accept POST query string parametersexpect those parameters in the request body.

You can list secrets as well. To do this, either issue a GET with the querystring parameter list=true, or you use the LIST HTTP verb. For the kv secretsengine, listing is allowed on directories only, which returns the keys at therequested path:

$ curl \ -H "X-Vault-Token: f3b09679-3001-009d-2b80-9c306ab81aa6" \ -X LIST \ http://127.0.0.1:8200/v1/secret/

The API documentation uses LIST as the HTTP verb, but you can still use GETwith the ?list=true query string.

To make an API with specific data in request body, issue a POST:

/v1/secret/foo

with a JSON body like:

{ "value": "bar"}

Here is an example of writing a secret using cURL:

$ curl \ -H "X-Vault-Token: f3b09679-3001-009d-2b80-9c306ab81aa6" \ -H "Content-Type: application/json" \ -X POST \ -d '{"data":{"value":"bar"}}' \ http://127.0.0.1:8200/v1/secret/baz

Vault currently considers PUT and POST to be synonyms. Rather than trust aclient's stated intentions, Vault engines can implement an existence check todiscover whether an operation is actually a create or update operation based onthe data already stored within Vault. This makes permission management via ACLsmore flexible.

A KVv2 example for the engine path of secret requires that URI isappended with data/ prior to the secret name (baz) such as:

$ curl \ -H "X-Vault-Token: f3b09679-3001-009d-2b80-9c306ab81aa6" \ -H "Content-Type: application/json" \ -X POST \ -d '{"data":{"value":"bar"}}' \ http://127.0.0.1:8200/v1/secret/data/baz

For more examples, please look at the Vault API client.

The X-Vault-Request Header

Requests that are sent to a Vault Agent that is configured to use therequire_request_header option must include the X-Vault-Request headerentry, e.g.:

$ curl \ -H "X-Vault-Token: f3b09679-3001-009d-2b80-9c306ab81aa6" \ -H "X-Vault-Request: true" \ -H "Content-Type: application/json" \ -X POST \ -d '{"value":"bar"}' \ http://127.0.0.1:8200/v1/secret/baz

The Vault CLI always adds this header to every request, regardless of whetherthe request is being sent to a Vault Agent or directly to a Vault Server. Inaddition, the Vault SDK always adds this header to every request.

To retrieve the help for any API within Vault, including mounted engines, authmethods, etc. then append ?help=1 to any URL. If you have valid permission toaccess the path, then the help text will be returned as a markdown-formatted blockin the help attribute of the response.

Additionally, with the OpenAPI generation in Vault, you will get back a smallOpenAPI document in the openapi attribute. This document is relevant for thepath you're looking up and any paths under it - also note paths in the OpenAPIdocument are relative to the initial path queried.

Example request:

$ curl \ -H "X-Vault-Token: f3b09679-3001-009d-2b80-9c306ab81aa6" \ http://127.0.0.1:8200/v1/secret?help=1

Example response:

{ "help": "## DESCRIPTION\n\nThis backend provides a versioned key-value store. The kv backend reads and\nwrites arbitrary secrets to the storage backend. The secrets are\nencrypted/decrypted by Vault: they are never stored unencrypted in the backend\nand the backend never has an opportunity to see the unencrypted value. Each key\ncan have a configured number of versions, and versions can be retrieved based on\ntheir version numbers.\n\n## PATHS\n\nThe following paths are supported by this backend. To view help for\nany of the paths below, use the help command with any route matching\nthe path pattern. Note that depending on the policy of your auth token,\nyou may or may not be able to access certain paths.\n\n ^.*$\n\n\n ^config$\n Configures settings for the KV store\n\n ^data/(?P<path>.*)$\n Write, Read, and Delete data in the Key-Value Store.\n\n ^delete/(?P<path>.*)$\n Marks one or more versions as deleted in the KV store.\n\n ^destroy/(?P<path>.*)$\n Permanently removes one or more versions in the KV store\n\n ^metadata/(?P<path>.*)$\n Configures settings for the KV store\n\n ^undelete/(?P<path>.*)$\n Undeletes one or more versions from the KV store.", "openapi": { "openapi": "3.0.2", "info": { "title": "HashiCorp Vault API", "description": "HTTP API that gives you full access to Vault. All API routes are prefixed with `/v1/`.", "version": "1.0.0", "license": { "name": "Mozilla Public License 2.0", "url": "https://www.mozilla.org/en-US/MPL/2.0" } }, "paths": { "/.*": {}, "/config": { "description": "Configures settings for the KV store", "x-vault-create-supported": true, "get": { "summary": "Read the backend level settings.", "tags": [ "secrets" ], "responses": { "200": { "description": "OK" } } }, ...[output truncated]... } }}

Error Response

A common JSON structure is always returned to return errors:

{ "errors": [ "message", "another message" ]}

This structure will be returned for any HTTP status greater than or equal to 400.

The following HTTP status codes are used throughout the API. Vault tries toadhere to these whenever possible, but in case it doesn't -- then feel free toraise a bug for our attention!

Note: Applications should be prepared to accept both 200 and 204 assuccess. 204 is simply an indication that there is no response body to parse,but API endpoints that indicate that they return a 204 may return a 200 ifwarnings are generated during the operation.

  • 200 - Success with data.
  • 204 - Success, no data returned.
  • 400 - Invalid request, missing or invalid data.
  • 403 - Forbidden, your authentication details are either incorrect, youdon't have access to this feature, or - if CORS is enabled - you made across-origin request from an origin that is not allowed to make suchrequests.
  • 404 - Invalid path. This can both mean that the path truly doesn't exist orthat you don't have permission to view a specific path. We use 404 in somecases to avoid state leakage.
  • 405 - Unsupported operation. You tried to use a method inappropriate tothe request path, e.g. a POST on an endpoint that only accepts GETs.
  • 412 - Precondition failed. Returned on Enterprise when a request can't beprocessed yet due to some missing eventually consistent data. Should be retried,perhaps with a little backoff.See Vault Eventual Consistency.
  • 429 - Default return code for health status of standby nodes. This willlikely change in the future.
  • 473 - Default return code for health status of performance standby nodes.
  • 500 - Internal server error. An internal error has occurred, try againlater. If the error persists, report a bug.
  • 502 - A request to Vault required Vault making a request to a third party;the third party responded with an error of some kind.
  • 503 - Vault is down for maintenance or is currently sealed. Try againlater.

Limits

A maximum request size of 32MB is imposed to prevent a denial of service attackwith arbitrarily large requests; this can be tuned per listener block inVault's server configuration file.

Top Articles
Latest Posts
Article information

Author: Madonna Wisozk

Last Updated: 03/23/2023

Views: 6090

Rating: 4.8 / 5 (68 voted)

Reviews: 83% of readers found this page helpful

Author information

Name: Madonna Wisozk

Birthday: 2001-02-23

Address: 656 Gerhold Summit, Sidneyberg, FL 78179-2512

Phone: +6742282696652

Job: Customer Banking Liaison

Hobby: Flower arranging, Yo-yoing, Tai chi, Rowing, Macrame, Urban exploration, Knife making

Introduction: My name is Madonna Wisozk, I am a attractive, healthy, thoughtful, faithful, open, vivacious, zany person who loves writing and wants to share my knowledge and understanding with you.