open-vault/website/content/api-docs/index.mdx

---
layout: api
page_title: HTTP API
description: Vault has an HTTP API that can be used to control every aspect of Vault.
---

# HTTP API

The Vault HTTP API gives you full access to Vault using [REST like HTTP verbs](https://en.wikipedia.org/wiki/Representational_state_transfer). 
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.

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 yet
promise backwards compatibility even with the v1 prefix. We'll remove this
warning when this policy changes. At this point in time the core API (that
is, `sys/` routes) change very infrequently, but various secrets engines/auth
methods/etc. sometimes have minor changes to accommodate new features as
they're developed.

## Transport

The API is expected to be accessed over a TLS connection at all times, with a
valid certificate that is verified by a well-behaved client. It is possible to
disable TLS verification for listeners, however, so API clients should expect
to 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 as
either the `X-Vault-Token` HTTP Header or as `Authorization` HTTP Header using
the `Bearer <token>` scheme.

Otherwise, a client token can be retrieved using an [authentication
engine](/vault/docs/auth).

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

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

## Parameter restrictions

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

## Namespaces

When using [Namespaces](/vault/docs/enterprise/namespaces) the final path of the API 
request is relative to the `X-Vault-Namespace` header. For instance, if a 
request 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 the 
`X-Vault-Namespace` header, Vault will match the corresponding namespace 
based on correlating user input. Similar path results may be achieved if 
`X-Vault-Namespace` is set to `ns1/` with the request path of `ns2/secret/foo` 
as well, or otherwise if `X-Vault-Namespace` is omitted entirely and instead a 
complete path is provided such as: `ns1/ns2/secret/foo`.

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

```shell-session
$ 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
```

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

## API Operations

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 does 
not require it from the clients request.

The demonstration below uses the [`KVv1` secrets engine](/vault/api-docs/secret/kv/kv-v1), which is a 
simple Key/Value store. Please read [the API documentation of KV secret engines](/vault/api-docs/secret/kv) 
for details of `KVv1` compared to `KVv2` and how they differ in their URI paths 
as 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:

```text
/v1/secret/foo
```

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

Here is an example of reading a secret using cURL:

```shell-session
$ 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 if 
those parameters are not sensitive, especially since  some load balancers will 
be able log these. Most endpoints that accept `POST` query string parameters 
expect those parameters in the request body.

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

```shell-session
$ 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 `GET`
with the `?list=true` query string.

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

```text
/v1/secret/foo
```

with a JSON body like:

```javascript
{
  "value": "bar"
}
```

Here is an example of writing a secret using cURL:

```shell-session
$ 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 a
client's stated intentions, Vault engines can implement an existence check to
discover whether an operation is actually a create or update operation based on
the data already stored within Vault. This makes permission management via ACLs
more flexible.

A [KVv2 example](/vault/api-docs/secret/kv/kv-v2#sample-request-3) for the engine path of `secret` requires that URI is 
appended with ***`data/`***  prior to the secret name (`baz`) such as:

```shell-session
$ 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][agent] that is configured to use the
`require_request_header` option must include the `X-Vault-Request` header
entry, e.g.:

```shell-session
$ 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 whether
the request is being sent to a Vault Agent or directly to a Vault Server. In
addition, the Vault SDK always adds this header to every request.

## Help

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

Additionally, with the [OpenAPI generation](/vault/api-docs/system/internal-specs-openapi) in Vault, you will get back a small
OpenAPI document in the `openapi` attribute. This document is relevant for the 
path you're looking up and any paths under it - also note paths in the OpenAPI 
document are relative to the initial path queried.


Example request:

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

Example response:

```javascript
{
  "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:

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

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

## HTTP Status Codes

The following HTTP status codes are used throughout the API. Vault tries to
adhere to these whenever possible, but in case it doesn't -- then feel free to 
[raise a bug](https://github.com/hashicorp/vault/issues) for our attention!

~> _Note_: Applications should be prepared to accept both `200` and `204` as
success. `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` if
warnings 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, you
  don't have access to this feature, or - if CORS is enabled - you made a
  cross-origin request from an origin that is not allowed to make such
  requests.
- `404` - Invalid path. This can both mean that the path truly doesn't exist or
  that you don't have permission to view a specific path. We use 404 in some
  cases to avoid state leakage.
- `405` - Unsupported operation.  You tried to use a method inappropriate to
  the request path, e.g. a POST on an endpoint that only accepts GETs.
- `412` - Precondition failed.  Returned on Enterprise when a request can't be
  processed yet due to some missing eventually consistent data.  Should be retried,
  perhaps with a little backoff.
  See [Vault Eventual Consistency](/vault/docs/enterprise/consistency).
- `429` - Default return code for health status of standby nodes. This will
  likely 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 again
  later. 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 again
  later.

## Limits

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

[agent]: /vault/docs/agent#listener-stanza