Skip to main content

HTTP API

The OpenBao HTTP API gives you full access to OpenBao using REST like HTTP verbs. Every aspect of OpenBao can be controlled using the APIs. The OpenBao CLI uses the HTTP API to access OpenBao 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.

warning

Backwards compatibility: At the current version, OpenBao 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 OpenBao 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.

Each auth method has one or more unauthenticated login endpoints. These endpoints can be reached without any authentication, and are used for authentication to OpenBao 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 OpenBao APIs require specifying path parameters. The path parameter cannot end in periods. Otherwise, OpenBao will return a 404 unsupported path error.

API operations​

Typically the request data, body and response data to and from OpenBao is in JSON. OpenBao 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, which is a simple Key/Value store. Please read the API documentation of KV secret engines 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:

/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 OpenBao 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 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:

$ 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:

/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

OpenBao currently considers PUT and POST to be synonyms. Rather than trust a client's stated intentions, OpenBao 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 OpenBao. This makes permission management via ACLs more flexible.

A KVv2 example for the engine path of secret requires that URI is appended 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 OpenBao API client.

The X-Vault-Request header​

Requests that are sent to a OpenBao Proxy that is configured to use the require_request_header option must include the X-Vault-Request header entry, 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 OpenBao CLI always adds this header to every request, regardless of whether the request is being sent to an OpenBao Agent or directly to an OpenBao Server. In addition, the OpenBao SDK always adds this header to every request.

Help​

To retrieve the help for any API within OpenBao, 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 in OpenBao, 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:

$ 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 OpenBao: 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": "OpenBao API",
      "description": "HTTP API that gives you full access to OpenBao. 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.

HTTP status codes​

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

warning

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.
info

Note: 404 is also returned on LIST endpoints with no results.

  • 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.
  • 429 - Default return code for health status of standby nodes. This will likely change in the future.
  • 500 - Internal server error. An internal error has occurred, try again later. If the error persists, report a bug.
  • 502 - A request to OpenBao required OpenBao making a request to a third party; the third party responded with an error of some kind.
  • 503 - OpenBao 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 OpenBao's server configuration file.