1--- 2layout: "api" 3page_title: "HTTP API" 4sidebar_title: "Overview" 5sidebar_current: "api-http-overview" 6description: |- 7 Vault has an HTTP API that can be used to control every aspect of Vault. 8--- 9 10# HTTP API 11 12The Vault HTTP API gives you full access to Vault via HTTP. Every aspect of 13Vault can be controlled via this API. The Vault CLI uses the HTTP API to access 14Vault. 15 16All API routes are prefixed with `/v1/`. 17 18This documentation is only for the v1 API, which is currently the only version. 19 20 ~> **Backwards compatibility:** At the current version, Vault does not yet 21 promise backwards compatibility even with the v1 prefix. We'll remove this 22 warning when this policy changes. At this point in time the core API (that 23 is, `sys/` routes) change very infrequently, but various secrets engines/auth 24 methods/etc. sometimes have minor changes to accommodate new features as 25 they're developed. 26 27## Transport 28 29The API is expected to be accessed over a TLS connection at all times, with a 30valid certificate that is verified by a well-behaved client. It is possible to 31disable TLS verification for listeners, however, so API clients should expect 32to have to do both depending on user settings. 33 34## Authentication 35 36Once Vault is unsealed, almost every other operation requires a _client token_. 37A user may have a client token sent to them. The client token must be sent as 38either the `X-Vault-Token` HTTP Header or as `Authorization` HTTP Header using 39the `Bearer <token>` scheme. 40 41Otherwise, a client token can be retrieved via [authentication 42backends](/docs/auth/index.html). 43 44Each auth method has one or more unauthenticated login endpoints. These 45endpoints can be reached without any authentication, and are used for 46authentication to Vault itself. These endpoints are specific to each auth 47method. 48 49Responses from auth login methods that generate an authentication token are 50sent back to the client via JSON. The resulting token should be saved on the 51client or passed via the `X-Vault-Token` or `Authorization` header for future requests. 52 53## Namespaces 54 55If using the [Namespaces](/docs/enterprise/namespaces/index.html) feature, API 56operations are relative to the namespace value passed in via the 57`X-Vault-Namespace` header. For instance, if the request path is to 58`secret/foo`, and the header is set to `ns1/ns2/`, the final request path Vault 59uses will be `ns1/ns2/secret/foo`. Note that it is semantically equivalent to 60use a full path rather than the `X-Vault-Namespace` header, as the operation in 61Vault will always look up the correct namespace based on the final given path. 62Thus, it would be equivalent to the above example to set `X-Vault-Namespace` to 63`ns1/` and a request path of `ns2/secret/foo`, or to not set 64`X-Vault-Namespace` at all and use a request path of `ns1/ns2/secret/foo`. 65 66For example, the following two commands result in equivalent requests: 67 68```shell 69$ curl \ 70 -H "X-Vault-Token: f3b09679-3001-009d-2b80-9c306ab81aa6" \ 71 -H "X-Vault-Namespace: ns1/ns2/" \ 72 -X GET \ 73 http://127.0.0.1:8200/v1/secret/foo 74``` 75 76```shell 77$ curl \ 78 -H "X-Vault-Token: f3b09679-3001-009d-2b80-9c306ab81aa6" \ 79 -X GET \ 80 http://127.0.0.1:8200/v1/ns1/ns2/secret/foo 81``` 82 83## API Operations 84 85With few documented exceptions, all request body data and response data from 86Vault is via JSON. Vault will set the `Content-Type` header appropriately but 87does not require that clients set it. 88 89Different plugins implement different APIs according to their functionality. 90The examples below are created with the `KVv1` backend, which acts like a very 91simple Key/Value store. Read the documentation for a particular backend for 92detailed information on its API; this simply provides a general overview. 93 94For `KVv1`, reading a secret via the HTTP API is done by issuing a GET: 95 96```text 97/v1/secret/foo 98``` 99 100This maps to `secret/foo` where `foo` is the key in the `secret/` mount, which 101is mounted by default on a fresh Vault install and is of type `kv`. 102 103Here is an example of reading a secret using cURL: 104 105```shell 106$ curl \ 107 -H "X-Vault-Token: f3b09679-3001-009d-2b80-9c306ab81aa6" \ 108 -X GET \ 109 http://127.0.0.1:8200/v1/secret/foo 110``` 111 112A few endpoints consume query parameters via `GET` calls, but only if those 113parameters are not sensitive, as some load balancers will log these. Most 114endpoints that consume parameters use `POST` instead and put the parameters in 115the request body. 116 117You can list secrets as well. To do this, either issue a GET with the query 118parameter `list=true`, or you can use the `LIST` HTTP verb. For the `kv` 119backend, listing is allowed on directories only, and returns the keys in the 120given directory: 121 122```shell 123$ curl \ 124 -H "X-Vault-Token: f3b09679-3001-009d-2b80-9c306ab81aa6" \ 125 -X LIST \ 126 http://127.0.0.1:8200/v1/secret/ 127``` 128 129The API documentation uses `LIST` as the HTTP verb, but you can still use `GET` 130with the `?list=true` query string. 131 132To use an API that consumes data via request body, issue a `POST` or `PUT`: 133 134```text 135/v1/secret/foo 136``` 137 138with a JSON body like: 139 140```javascript 141{ 142 "value": "bar" 143} 144``` 145 146Here is an example of writing a secret using cURL: 147 148```shell 149$ curl \ 150 -H "X-Vault-Token: f3b09679-3001-009d-2b80-9c306ab81aa6" \ 151 -H "Content-Type: application/json" \ 152 -X POST \ 153 -d '{"value":"bar"}' \ 154 http://127.0.0.1:8200/v1/secret/baz 155``` 156 157Vault currently considers `PUT` and `POST` to be synonyms. Rather than trust a 158client's stated intentions, Vault backends can implement an existence check to 159discover whether an operation is actually a create or update operation based on 160the data already stored within Vault. This makes permission management via ACLs 161more flexible. 162 163For more examples, please look at the Vault API client. 164 165## Help 166 167To retrieve the help for any API within Vault, including mounted backends, auth 168methods, etc. then append `?help=1` to any URL. If you have valid permission to 169access the path, then the help text will be return a markdown-formatted block in the `help` attribute of the response. 170 171Additionally, with the [OpenAPI generation](/api/system/internal-specs-openapi.html) in Vault, you will get back a small 172OpenAPI 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. 173 174Example request: 175 176```shell 177$ curl \ 178 -H "X-Vault-Token: f3b09679-3001-009d-2b80-9c306ab81aa6" \ 179 http://127.0.0.1:8200/v1/secret?help=1 180``` 181 182Example response: 183 184```javascript 185 186{ 187 "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.", 188 "openapi": { 189 "openapi": "3.0.2", 190 "info": { 191 "title": "HashiCorp Vault API", 192 "description": "HTTP API that gives you full access to Vault. All API routes are prefixed with `/v1/`.", 193 "version": "1.0.0", 194 "license": { 195 "name": "Mozilla Public License 2.0", 196 "url": "https://www.mozilla.org/en-US/MPL/2.0" 197 } 198 }, 199 "paths": { 200 "/.*": {}, 201 "/config": { 202 "description": "Configures settings for the KV store", 203 "x-vault-create-supported": true, 204 "get": { 205 "summary": "Read the backend level settings.", 206 "tags": [ 207 "secrets" 208 ], 209 "responses": { 210 "200": { 211 "description": "OK" 212 } 213 } 214 }, 215 ...[output truncated]... 216 } 217 } 218} 219``` 220 221 222## Error Response 223 224A common JSON structure is always returned to return errors: 225 226```javascript 227{ 228 "errors": [ 229 "message", 230 "another message" 231 ] 232} 233``` 234 235This structure will be sent down for any HTTP status greater than 236or equal to 400. 237 238## HTTP Status Codes 239 240The following HTTP status codes are used throughout the API. Vault tries to 241adhere to these whenever possible, but in some cases may not -- feel free to 242file a bug in that case to point our attention to it! 243 244~> *Note*: Applications should be prepared to accept both `200` and `204` as 245success. `204` is simply an indication that there is no response body to parse, 246but API endpoints that indicate that they return a `204` may return a `200` if 247warnings are generated during the operation. 248 249- `200` - Success with data. 250- `204` - Success, no data returned. 251- `400` - Invalid request, missing or invalid data. 252- `403` - Forbidden, your authentication details are either incorrect, you 253 don't have access to this feature, or - if CORS is enabled - you made a 254 cross-origin request from an origin that is not allowed to make such 255 requests. 256- `404` - Invalid path. This can both mean that the path truly doesn't exist or 257 that you don't have permission to view a specific path. We use 404 in some 258 cases to avoid state leakage. 259- `429` - Default return code for health status of standby nodes. This will 260 likely change in the future. 261- `473` - Default return code for health status of performance standby nodes. 262- `500` - Internal server error. An internal error has occurred, try again 263 later. If the error persists, report a bug. 264- `502` - A request to Vault required Vault making a request to a third party; 265 the third party responded with an error of some kind. 266- `503` - Vault is down for maintenance or is currently sealed. Try again 267 later. 268 269## Limits 270 271A maximum request size of 32MB is imposed to prevent a denial of service attack 272with arbitrarily large requests; this can be tuned per `listener` block in 273Vault's server configuration file. 274