<commit_before>---
layout: "http"
page_title: "HTTP API"
sidebar_current: "docs-http-overview"
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 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 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`

In order to write a secret to `secret/foo` for instance, issue a POST on the following URL:

`/v1/secret/foo`

with the following JSON body:

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

Here is an example of writing a secret using cURL:

`curl -H "X-Vault-Token: <PASSWORD>" -H "Content-Type: application/json" -X POST -d '{"value":"bar"}' http://127.0.0.1:8200/v1/secret/baz`

Also ensure that `X-Vault-Token` is present in the request header





## 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<commit_msg>Cleanup style on http index docs<commit_after>---
layout: "http"
page_title: "HTTP API"
sidebar_current: "docs-http-overview"
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 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:

```text
/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:

```shell
curl \
  -H "X-Vault-Token: <PASSWORD>" \
  -X GET \
   http://127.0.0.1:8200/v1/secret/foo
```

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

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

with a JSON body like:

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

Here is an example of writing a secret using cURL:

```shell
curl \
  -H "X-Vault-Token: <PASSWORD>" \
  -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
{'fraction_non_alphanumeric': 0.07499561941475381, 'fraction_numerical': 0.014543543017347118, 'mean_word_length': 4.015817223198594, 'pattern_counts': {'":': 4, '<': 6, '<?xml version=': 0, '>': 8, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 4, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2750743', 'n_tokens_mistral': 1712, 'n_tokens_neox': 1615, 'n_words': 852}