mootpt f782e7382e pointed authentication backend to proper location

pointed authentication backend to proper location

2015-07-06 10:42:14 -07:00

4 KiB

Raw Blame History

layout	page_title	sidebar_current	description
http	HTTP API	docs-http-overview	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 via HTTP. Every aspect of Vault can be controlled via this API. The Vault CLI uses the HTTP API to access Vault.

Version Prefix

All API routes are prefixed with /v1/.

This documentation is only for the v1 API.

~> 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. We expect we'll reach API stability by Vault 0.3.

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 the Vault is unsealed, every other operation requires a client token. A user may have a client token explicitly. The client token must be sent as the token cookie or the X-Vault-Token HTTP header.

Otherwise, a client token can be retrieved via authentication backends.

Each authentication backend will have one or more unauthenticated login endpoints. These endpoints can be reached without any authentication, and are used for authentication itself. These endpoints are specific to each authentication backend.

Login endpoints for authentication backends that generate an identity will be sent down with a Set-Cookie header as well as via JSON. If you have a well-behaved HTTP client, then authentication information will automatically be saved and sent to the Vault API.

Reading and Writing Secrets

Reading a secret via the HTTP API is done by issuing a GET using the following URL:

/v1/secret/foo

This maps to secret/foo where foo is the key in the secret/ backend/

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

To write a secret, issue a POST on the following URL:

/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 '{"value":"bar"}' \
  http://127.0.0.1:8200/v1/secret/baz

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

Help

To retrieve the help for any API within Vault, including mounted backends, credential providers, etc. then append ?help=1 to any URL. If you have valid permission to access the path, then the help text will be returned with the following structure:

{
  "help": "help text"
}

Error Response

A common JSON structure is always returned to return errors:

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

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

HTTP Status Codes

The following HTTP status codes are used throughout the API.

200 - Success with data.
204 - Success, no data returned.
400 - Invalid request, missing or invalid data. See the "validation" section for more details on the error response.
401 - Unauthorized, your authentication details are either incorrect or you don't have access to this feature.
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.
429 - Rate limit exceeded. Try again after waiting some period of time.
500 - Internal server error. An internal error has occurred, try again later. If the error persists, report a bug.
503 - Vault is down for maintenance or is currently sealed. Try again later.

4 KiB Raw Blame History