mirror of
https://github.com/hashicorp/vault.git
synced 2026-04-01 15:15:01 -04:00
Redo docs for system backend
This commit updates the API documentation for the system backend to break things apart on a per-page basis and provide specific examples. This pattern will give more flexibility for future documentation as well.
This commit is contained in:
Seth Vargo
parent
01865c6641
commit
efd532536f
62 changed files with 2460 additions and 2384 deletions
|
|
@ -2,6 +2,15 @@
|
|||
// API
|
||||
// --------------------------------------------------
|
||||
|
||||
body.layout-http {
|
||||
// Extend bootstrap's table and table-striped classes on generic markdown
|
||||
// tables. This enables GHFM tables instead of HTML.
|
||||
table {
|
||||
@extend .table;
|
||||
@extend .table-striped;
|
||||
}
|
||||
}
|
||||
|
||||
.bs-api-section dl, dl.api {
|
||||
margin-top: 30px;
|
||||
line-height: 20px;
|
||||
|
|
|
|||
|
|
@ -1,53 +0,0 @@
|
|||
---
|
||||
layout: "http"
|
||||
page_title: "HTTP API: /sys/audit-hash"
|
||||
sidebar_current: "docs-http-audits-hash"
|
||||
description: |-
|
||||
The `/sys/audit-hash` endpoint is used to hash data using an audit backend's hash function and salt.
|
||||
---
|
||||
|
||||
# /sys/audit-hash
|
||||
|
||||
## POST
|
||||
|
||||
<dl>
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Hash the given input data with the specified audit backend's hash function
|
||||
and salt. This endpoint can be used to discover whether a given plaintext
|
||||
string (the `input` parameter) appears in the audit log in obfuscated form.
|
||||
Note that the audit log records requests and responses; since the Vault API
|
||||
is JSON-based, any binary data returned from an API call (such as a
|
||||
DER-format certificate) is base64-encoded by the Vault server in the
|
||||
response, and as a result such information should also be base64-encoded to
|
||||
supply into the `input` parameter.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>POST</dd>
|
||||
|
||||
<dt>URL</dt>
|
||||
<dd>`/sys/audit-hash/<path>`</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>
|
||||
<ul>
|
||||
<li>
|
||||
<span class="param">input</span>
|
||||
<span class="param-flags">required</span>
|
||||
The input string to hash.
|
||||
</li>
|
||||
</ul>
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>
|
||||
|
||||
```javascript
|
||||
{
|
||||
"hash": "hmac-sha256:08ba357e274f528065766c770a639abf6809b39ccfd37c2a3157c7f51954da0a"
|
||||
}
|
||||
```
|
||||
|
||||
</dd>
|
||||
</dl>
|
||||
|
|
@ -1,110 +0,0 @@
|
|||
---
|
||||
layout: "http"
|
||||
page_title: "HTTP API: /sys/audit"
|
||||
sidebar_current: "docs-http-audits-audits"
|
||||
description: |-
|
||||
The `/sys/audit` endpoint is used to enable and disable audit backends.
|
||||
---
|
||||
|
||||
# /sys/audit
|
||||
|
||||
## GET
|
||||
|
||||
<dl>
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
List the mounted audit backends. _This endpoint requires `sudo`
|
||||
capability._
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>GET</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>
|
||||
None
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>
|
||||
|
||||
```javascript
|
||||
{
|
||||
"file": {
|
||||
"type": "file",
|
||||
"description": "Store logs in a file",
|
||||
"options": {
|
||||
"path": "/var/log/file"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
## PUT
|
||||
|
||||
<dl>
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Enable an audit backend. _This endpoint requires `sudo` capability._
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>PUT</dd>
|
||||
|
||||
<dt>URL</dt>
|
||||
<dd>`/sys/audit/<path>`</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>
|
||||
<ul>
|
||||
<li>
|
||||
<span class="param">type</span>
|
||||
<span class="param-flags">required</span>
|
||||
The type of the audit backend.
|
||||
</li>
|
||||
<li>
|
||||
<span class="param">description</span>
|
||||
<span class="param-flags">optional</span>
|
||||
A description of the audit backend for operators.
|
||||
</li>
|
||||
<li>
|
||||
<span class="param">options</span>
|
||||
<span class="param-flags">optional</span>
|
||||
An object of options to configure the backend. This is
|
||||
dependent on the backend type. Please consult the documentation
|
||||
for the backend type you intend to use.
|
||||
</li>
|
||||
</ul>
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>`204` response code.
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
## DELETE
|
||||
|
||||
<dl>
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Disable the given audit backend. _This endpoint requires `sudo`
|
||||
capability._
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>DELETE</dd>
|
||||
|
||||
<dt>URL</dt>
|
||||
<dd>`/sys/audit/<path>`</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>None
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>`204` response code.
|
||||
</dd>
|
||||
</dl>
|
||||
|
|
@ -1,182 +0,0 @@
|
|||
---
|
||||
layout: "http"
|
||||
page_title: "HTTP API: /sys/auth"
|
||||
sidebar_current: "docs-http-auth-auth"
|
||||
description: |-
|
||||
The `/sys/auth` endpoint is used to manage auth backends in Vault.
|
||||
---
|
||||
|
||||
# /sys/auth
|
||||
|
||||
## GET
|
||||
|
||||
<dl>
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Lists all the enabled auth backends.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>GET</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>
|
||||
None
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>
|
||||
|
||||
```javascript
|
||||
{
|
||||
"github": {
|
||||
"type": "github",
|
||||
"description": "GitHub auth"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
## POST
|
||||
|
||||
<dl>
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Enable a new auth backend. The auth backend can be accessed and configured
|
||||
via the auth path specified in the URL. This auth path will be exposed
|
||||
under the `auth` prefix. For example, enabling with the `/sys/auth/foo` URL
|
||||
will make the backend available at `/auth/foo`. _This endpoint requires
|
||||
`sudo` capability on the final path._
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>POST</dd>
|
||||
|
||||
<dt>URL</dt>
|
||||
<dd>`/sys/auth/<auth_path>`</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>
|
||||
<ul>
|
||||
<li>
|
||||
<span class="param">type</span>
|
||||
<span class="param-flags">required</span>
|
||||
The name of the auth backend type, such as "github"
|
||||
</li>
|
||||
<li>
|
||||
<span class="param">description</span>
|
||||
<span class="param-flags">optional</span>
|
||||
A human-friendly description of the auth backend.
|
||||
</li>
|
||||
</ul>
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>`204` response code.
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
## DELETE
|
||||
|
||||
<dl>
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Disable the auth backend at the given auth path. _This endpoint requires
|
||||
`sudo` capability on the final path._
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>DELETE</dd>
|
||||
|
||||
<dt>URL</dt>
|
||||
<dd>`/sys/auth/<auth_path>`</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>None
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>`204` response code.
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
# /sys/auth/[auth-path]/tune
|
||||
|
||||
## GET
|
||||
|
||||
<dl>
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Read the given auth path's configuration. Returns the current time
|
||||
in seconds for each TTL, which may be the system default or a auth path
|
||||
specific value. _This endpoint requires `sudo` capability on the final
|
||||
path, but the same functionality can be achieved without `sudo` via
|
||||
`sys/mounts/auth/[auth-path]/tune`._
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>GET</dd>
|
||||
|
||||
<dt>URL</dt>
|
||||
<dd>`/sys/auth/[auth-path]/tune`</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>
|
||||
None
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>
|
||||
|
||||
```javascript
|
||||
{
|
||||
"default_lease_ttl": 3600,
|
||||
"max_lease_ttl": 7200
|
||||
}
|
||||
```
|
||||
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
## POST
|
||||
|
||||
<dl>
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Tune configuration parameters for a given auth path. _This endpoint
|
||||
requires `sudo` capability on the final path, but the same functionality
|
||||
can be achieved without `sudo` via `sys/mounts/auth/[auth-path]/tune`._
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>POST</dd>
|
||||
|
||||
<dt>URL</dt>
|
||||
<dd>`/sys/auth/[auth-path]/tune`</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>
|
||||
<ul>
|
||||
<li>
|
||||
<span class="param">default_lease_ttl</span>
|
||||
<span class="param-flags">optional</span>
|
||||
The default time-to-live. If set on a specific auth path,
|
||||
overrides the global default. A value of "system" or "0"
|
||||
are equivalent and set to the system default TTL.
|
||||
</li>
|
||||
<li>
|
||||
<span class="param">max_lease_ttl</span>
|
||||
<span class="param-flags">optional</span>
|
||||
The maximum time-to-live. If set on a specific auth path,
|
||||
overrides the global default. A value of "system" or "0"
|
||||
are equivalent and set to the system max TTL.
|
||||
</li>
|
||||
</ul>
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>`204` response code.
|
||||
</dd>
|
||||
</dl>
|
||||
|
|
@ -1,48 +0,0 @@
|
|||
---
|
||||
layout: "http"
|
||||
page_title: "HTTP API: /sys/capabilities-accessor"
|
||||
sidebar_current: "docs-http-auth-capabilities-accessor"
|
||||
description: |-
|
||||
The `/sys/capabilities-accessor` endpoint is used to fetch the capabilities of the token associated with an accessor, on the given path.
|
||||
---
|
||||
|
||||
# /sys/capabilities-accessor
|
||||
|
||||
## POST
|
||||
|
||||
<dl>
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Returns the capabilities of the token associated with an accessor, on the given path.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>POST</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>
|
||||
<ul>
|
||||
<li>
|
||||
<span class="param">accessor</span>
|
||||
<span class="param-flags">required</span>
|
||||
Accessor of the token.
|
||||
</li>
|
||||
<li>
|
||||
<span class="param">path</span>
|
||||
<span class="param-flags">required</span>
|
||||
Path on which the token's capabilities will be checked.
|
||||
</li>
|
||||
</ul>
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>
|
||||
|
||||
```javascript
|
||||
{
|
||||
"capabilities": ["read", "list"]
|
||||
}
|
||||
```
|
||||
|
||||
</dd>
|
||||
</dl>
|
||||
|
|
@ -1,44 +0,0 @@
|
|||
---
|
||||
layout: "http"
|
||||
page_title: "HTTP API: /sys/capabilities-self"
|
||||
sidebar_current: "docs-http-auth-capabilities-self"
|
||||
description: |-
|
||||
The `/sys/capabilities-self` endpoint is used to fetch the capabilities of client token on a given path.
|
||||
---
|
||||
|
||||
# /sys/capabilities-self
|
||||
|
||||
## POST
|
||||
|
||||
<dl>
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Returns the capabilities of client token on the given path.
|
||||
Client token is the Vault token with which this API call is made.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>POST</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>
|
||||
<ul>
|
||||
<li>
|
||||
<span class="param">path</span>
|
||||
<span class="param-flags">required</span>
|
||||
Path on which the client token's capabilities will be checked.
|
||||
</li>
|
||||
</ul>
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>
|
||||
|
||||
```javascript
|
||||
{
|
||||
"capabilities": ["read", "list"]
|
||||
}
|
||||
```
|
||||
|
||||
</dd>
|
||||
</dl>
|
||||
|
|
@ -1,48 +0,0 @@
|
|||
---
|
||||
layout: "http"
|
||||
page_title: "HTTP API: /sys/capabilities"
|
||||
sidebar_current: "docs-http-auth-capabilities"
|
||||
description: |-
|
||||
The `/sys/capabilities` endpoint is used to fetch the capabilities of a token on a given path.
|
||||
---
|
||||
|
||||
# /sys/capabilities
|
||||
|
||||
## POST
|
||||
|
||||
<dl>
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Returns the capabilities of the token on the given path.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>POST</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>
|
||||
<ul>
|
||||
<li>
|
||||
<span class="param">token</span>
|
||||
<span class="param-flags">required</span>
|
||||
Token for which capabilities are being queried.
|
||||
</li>
|
||||
<li>
|
||||
<span class="param">path</span>
|
||||
<span class="param-flags">required</span>
|
||||
Path on which the token's capabilities will be checked.
|
||||
</li>
|
||||
</ul>
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>
|
||||
|
||||
```javascript
|
||||
{
|
||||
"capabilities": ["read", "list"]
|
||||
}
|
||||
```
|
||||
|
||||
</dd>
|
||||
</dl>
|
||||
|
|
@ -1,133 +0,0 @@
|
|||
---
|
||||
layout: "http"
|
||||
page_title: "HTTP API: /sys/config/auditing"
|
||||
sidebar_current: "docs-http-config-auditing"
|
||||
description: |-
|
||||
The `/sys/config/auditing` endpoint is used to configure auditing settings.
|
||||
---
|
||||
|
||||
# /sys/config/auditing/request-headers
|
||||
|
||||
## GET
|
||||
|
||||
<dl>
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
List the request headers that are configured to be audited. _This endpoint requires `sudo`
|
||||
capability._
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>GET</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>
|
||||
None
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>
|
||||
|
||||
```javascript
|
||||
{
|
||||
"headers": {
|
||||
"X-Forwarded-For": {
|
||||
"hmac":true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
# /sys/config/auditing/request-headers/
|
||||
|
||||
## GET
|
||||
|
||||
<dl>
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
List the information for the given request header. _This endpoint requires `sudo`
|
||||
capability._
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>GET</dd>
|
||||
|
||||
<dt>URL</dt>
|
||||
<dd>`/sys/config/auditing/request-headers/<name>`</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>
|
||||
None
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>
|
||||
|
||||
```javascript
|
||||
{
|
||||
"X-Forwarded-For": {
|
||||
"hmac":true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
## PUT
|
||||
|
||||
<dl>
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Enable auditing of a header. _This endpoint requires `sudo` capability._
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>PUT</dd>
|
||||
|
||||
<dt>URL</dt>
|
||||
<dd>`/sys/config/auditing/request-headers/<name>`</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>
|
||||
<ul>
|
||||
<li>
|
||||
<span class="param">hmac</span>
|
||||
<span class="param-flags">optional</span>
|
||||
Bool, if this header's value should be hmac'ed in the audit logs.
|
||||
Defaults to false.
|
||||
</li>
|
||||
</ul>
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>`204` response code.
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
## DELETE
|
||||
|
||||
<dl>
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Disable auditing of the given request header. _This endpoint requires `sudo`
|
||||
capability._
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>DELETE</dd>
|
||||
|
||||
<dt>URL</dt>
|
||||
<dd>`/sys/config/auditing/request-headers/<name>`</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>None
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>`204` response code.
|
||||
</dd>
|
||||
</dl>
|
||||
|
|
@ -1,188 +0,0 @@
|
|||
---
|
||||
layout: "http"
|
||||
page_title: "HTTP API: /sys/generate-root/"
|
||||
sidebar_current: "docs-http-sys-generate-root"
|
||||
description: |-
|
||||
The `/sys/generate-root/` endpoints are used to create a new root key for Vault.
|
||||
---
|
||||
|
||||
# /sys/generate-root/attempt
|
||||
|
||||
## GET
|
||||
|
||||
<dl>
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Reads the configuration and progress of the current root generation
|
||||
attempt.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>GET</dd>
|
||||
|
||||
<dt>URL</dt>
|
||||
<dd>`/sys/generate-root/attempt`</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>
|
||||
None
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>
|
||||
If a root generation is started, `progress` is how many unseal keys have
|
||||
been provided for this generation attempt, where `required` must be reached
|
||||
to complete. The `nonce` for the current attempt and whether the attempt is
|
||||
complete is also displayed. If a PGP key is being used to encrypt the final
|
||||
root token, its fingerprint will be returned. Note that if an OTP is being
|
||||
used to encode the final root token, it will never be returned.
|
||||
|
||||
```javascript
|
||||
{
|
||||
"started": true,
|
||||
"nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63",
|
||||
"progress": 1,
|
||||
"required": 3,
|
||||
"encoded_root_token": "",
|
||||
"pgp_fingerprint": "",
|
||||
"complete": false
|
||||
}
|
||||
```
|
||||
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
## PUT
|
||||
|
||||
<dl>
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Initializes a new root generation attempt. Only a single root generation
|
||||
attempt can take place at a time. One (and only one) of `otp` or `pgp_key`
|
||||
are required.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>PUT</dd>
|
||||
|
||||
<dt>URL</dt>
|
||||
<dd>`/sys/generate-root/attempt`</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>
|
||||
<ul>
|
||||
<li>
|
||||
<span class="param">otp</span>
|
||||
<span class="param-flags">optional</span>
|
||||
A base64-encoded 16-byte value. The raw bytes of the token will be
|
||||
XOR'd with this value before being returned to the final unseal key
|
||||
provider.
|
||||
</li>
|
||||
<li>
|
||||
<span class="param">pgp_key</span>
|
||||
<span class="param-flags">optional</span>
|
||||
A base64-encoded PGP public key. The raw bytes of the token will be
|
||||
encrypted with this value before being returned to the final unseal key
|
||||
provider.
|
||||
</li>
|
||||
</ul>
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>
|
||||
The current progress.
|
||||
|
||||
```javascript
|
||||
{
|
||||
"started": true,
|
||||
"nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63",
|
||||
"progress": 1,
|
||||
"required": 3,
|
||||
"encoded_root_token": "",
|
||||
"pgp_fingerprint": "816938b8a29146fbe245dd29e7cbaf8e011db793",
|
||||
"complete": false
|
||||
}
|
||||
```
|
||||
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
## DELETE
|
||||
|
||||
<dl>
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Cancels any in-progress root generation attempt. This clears any progress
|
||||
made. This must be called to change the OTP or PGP key being used.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>DELETE</dd>
|
||||
|
||||
<dt>URL</dt>
|
||||
<dd>`/sys/generate-root/attempt`</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>None
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>`204` response code.
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
# /sys/generate-root/update
|
||||
|
||||
## PUT
|
||||
|
||||
<dl>
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Enter a single master key share to progress the root generation attempt.
|
||||
If the threshold number of master key shares is reached, Vault will
|
||||
complete the root generation and issue the new token. Otherwise, this API
|
||||
must be called multiple times until that threshold is met. The attempt
|
||||
nonce must be provided with each call.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>PUT</dd>
|
||||
|
||||
<dt>URL</dt>
|
||||
<dd>`/sys/generate-root/update`</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>
|
||||
<ul>
|
||||
<li>
|
||||
<span class="param">key</span>
|
||||
<span class="param-flags">required</span>
|
||||
A single master share key.
|
||||
</li>
|
||||
<li>
|
||||
<span class="param">nonce</span>
|
||||
<span class="param-flags">required</span>
|
||||
The nonce of the attempt.
|
||||
</li>
|
||||
</ul>
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>
|
||||
A JSON-encoded object indicating the attempt nonce, and completion status,
|
||||
and the encoded root token, if the attempt is complete.
|
||||
|
||||
```javascript
|
||||
{
|
||||
"started": true,
|
||||
"nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63",
|
||||
"progress": 3,
|
||||
"required": 3,
|
||||
"pgp_fingerprint": "",
|
||||
"complete": true,
|
||||
"encoded_root_token": "FPzkNBvwNDeFh4SmGA8c+w=="
|
||||
}
|
||||
```
|
||||
|
||||
</dd>
|
||||
</dl>
|
||||
|
|
@ -1,81 +0,0 @@
|
|||
---
|
||||
layout: "http"
|
||||
page_title: "HTTP API: /sys/health"
|
||||
sidebar_current: "docs-http-debug-health"
|
||||
description: |-
|
||||
The '/sys/health' endpoint is used to check the health status of Vault.
|
||||
---
|
||||
|
||||
# /sys/health
|
||||
|
||||
<dl>
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Returns the health status of Vault. This matches the semantics of a
|
||||
Consul HTTP health check and provides a simple way to monitor the
|
||||
health of a Vault instance.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>GET/HEAD</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>
|
||||
<ul>
|
||||
<li>
|
||||
<span class="param">standbyok</span>
|
||||
<span class="param-flags">optional</span>
|
||||
A query parameter provided to indicate that being a standby should
|
||||
still return the active status code instead of the standby code
|
||||
</li>
|
||||
<li>
|
||||
<span class="param">activecode</span>
|
||||
<span class="param-flags">optional</span>
|
||||
A query parameter provided to indicate the status code that should
|
||||
be returned for an active node instead of the default of `200`
|
||||
</li>
|
||||
<li>
|
||||
<span class="param">standbycode</span>
|
||||
<span class="param-flags">optional</span>
|
||||
A query parameter provided to indicate the status code that should
|
||||
be returned for a standby node instead of the default of `429`
|
||||
</li>
|
||||
<li>
|
||||
<span class="param">sealedcode</span>
|
||||
<span class="param-flags">optional</span>
|
||||
A query parameter provided to indicate the status code that should
|
||||
be returned for a sealed node instead of the default of `503`
|
||||
</li>
|
||||
<li>
|
||||
<span class="param">uninitcode</span>
|
||||
<span class="param-flags">optional</span>
|
||||
A query parameter provided to indicate the status code that should
|
||||
be returned for an uninitialized Vault instead of the default of
|
||||
`501`
|
||||
</li>
|
||||
</ul>
|
||||
</dd>
|
||||
|
||||
<dt>Returns (only with GET)</dt>
|
||||
<dd>
|
||||
|
||||
```javascript
|
||||
{
|
||||
"cluster_id": "c9abceea-4f46-4dab-a688-5ce55f89e228",
|
||||
"cluster_name": "vault-cluster-5515c810",
|
||||
"version": "0.6.1-dev"
|
||||
"server_time_utc": 1469555798,
|
||||
"standby": false,
|
||||
"sealed": false,
|
||||
"initialized": true
|
||||
}
|
||||
```
|
||||
|
||||
Default Status Codes (GET/HEAD):
|
||||
|
||||
* `200` if initialized, unsealed, and active.
|
||||
* `429` if unsealed and standby.
|
||||
* `501` if not initialized.
|
||||
* `503` if sealed.
|
||||
</dd>
|
||||
</dl>
|
||||
|
|
@ -1,130 +0,0 @@
|
|||
---
|
||||
layout: "http"
|
||||
page_title: "HTTP API: /sys/init"
|
||||
sidebar_current: "docs-http-sys-init"
|
||||
description: |-
|
||||
The '/sys/init' endpoint is used to initialize a new Vault.
|
||||
---
|
||||
|
||||
# /sys/init
|
||||
|
||||
## GET
|
||||
|
||||
<dl>
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Return the initialization status of a Vault.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>GET</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>None</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>
|
||||
|
||||
```javascript
|
||||
{
|
||||
"initialized": true
|
||||
}
|
||||
```
|
||||
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
## PUT
|
||||
|
||||
<dl>
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Initializes a new Vault. The Vault must not have been previously
|
||||
initialized. The recovery options, as well as the stored shares option, are
|
||||
only available when using Vault HSM.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>PUT</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>
|
||||
<ul>
|
||||
<li>
|
||||
<span class="param">root_token_pgp_key</span>
|
||||
<span class="param-flags">optional</span>
|
||||
A PGP public key used to encrypt the initial root token. The key
|
||||
must be base64-encoded from its original binary representation.
|
||||
</li>
|
||||
<li>
|
||||
<span class="param">secret_shares</span>
|
||||
<span class="param-flags">required</span>
|
||||
The number of shares to split the master key into.
|
||||
</li>
|
||||
<li>
|
||||
<span class="param">secret_threshold</span>
|
||||
<span class="param-flags">required</span>
|
||||
The number of shares required to reconstruct the master key. This must
|
||||
be less than or equal to <code>secret_shares</code>. If using Vault HSM
|
||||
with auto-unsealing, this value must be the same as
|
||||
<code>secret_shares</code>.
|
||||
</li>
|
||||
<li>
|
||||
<span class="param">pgp_keys</span>
|
||||
<span class="param-flags">optional</span>
|
||||
An array of PGP public keys used to encrypt the output unseal keys.
|
||||
Ordering is preserved. The keys must be base64-encoded from their
|
||||
original binary representation. The size of this array must be the
|
||||
same as <code>secret_shares</code>.
|
||||
</li>
|
||||
<li>
|
||||
<span class="param">stored_shares</span>
|
||||
<span class="param-flags">required</span>
|
||||
The number of shares that should be encrypted by the HSM and stored for
|
||||
auto-unsealing (Vault HSM only). Currently must be the same as
|
||||
<code>secret_shares</code>.
|
||||
</li>
|
||||
<li>
|
||||
<span class="param">recovery_shares</span>
|
||||
<span class="param-flags">required</span>
|
||||
The number of shares to split the recovery key into (Vault HSM only).
|
||||
</li>
|
||||
<li>
|
||||
<span class="param">recovery_threshold</span>
|
||||
<span class="param-flags">required</span>
|
||||
The number of shares required to reconstruct the recovery key (Vault
|
||||
HSM only). This must be less than or equal to
|
||||
<code>recovery_shares</code>.
|
||||
</li>
|
||||
<li>
|
||||
<span class="param">recovery_pgp_keys</span>
|
||||
<span class="param-flags">optional</span>
|
||||
An array of PGP public keys used to encrypt the output recovery keys
|
||||
(Vault HSM only). Ordering is preserved. The keys must be
|
||||
base64-encoded from their original binary representation. The size of
|
||||
this array must be the same as <code>recovery_shares</code>.
|
||||
</li>
|
||||
</ul>
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>
|
||||
A JSON-encoded object including the (possibly encrypted, if
|
||||
<code>pgp_keys</code> was provided) master keys, base 64 encoded master keys and initial root token:
|
||||
|
||||
```javascript
|
||||
{
|
||||
"keys": ["one", "two", "three"],
|
||||
"keys_base64": ["cR9No5cBC", "F3VLrkOo", "zIDSZNGv"],
|
||||
"root_token": "foo"
|
||||
}
|
||||
```
|
||||
|
||||
</dd>
|
||||
|
||||
<dt>See Also</dt>
|
||||
<dd>
|
||||
For more information on the PGP/Keybase.io process please see the
|
||||
[Vault GPG and Keybase integration documentation](/docs/concepts/pgp-gpg-keybase.html).
|
||||
</dd>
|
||||
</dl>
|
||||
|
|
@ -1,38 +0,0 @@
|
|||
---
|
||||
layout: "http"
|
||||
page_title: "HTTP API: /sys/key-status"
|
||||
sidebar_current: "docs-http-rotate-key-status"
|
||||
description: |-
|
||||
The '/sys/key-status' endpoint is used to query info about the current encryption key of Vault.
|
||||
---
|
||||
|
||||
# /sys/key-status
|
||||
|
||||
<dl>
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Returns information about the current encryption key used by Vault.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>GET</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>
|
||||
None
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>
|
||||
The "term" parameter is the sequential key number, and "install_time" is the time that
|
||||
encryption key was installed.
|
||||
|
||||
```javascript
|
||||
{
|
||||
"term": 3,
|
||||
"install_time": "2015-05-29T14:50:46.223692553-07:00"
|
||||
}
|
||||
```
|
||||
|
||||
</dd>
|
||||
</dl>
|
||||
|
|
@ -1,37 +0,0 @@
|
|||
---
|
||||
layout: "http"
|
||||
page_title: "HTTP API: /sys/leader"
|
||||
sidebar_current: "docs-http-ha-leader"
|
||||
description: |-
|
||||
The '/sys/leader' endpoint is used to check the high availability status and current leader of Vault.
|
||||
---
|
||||
|
||||
# /sys/leader
|
||||
|
||||
<dl>
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Returns the high availability status and current leader instance of Vault.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>GET</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>
|
||||
None
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>
|
||||
|
||||
```javascript
|
||||
{
|
||||
"ha_enabled": true,
|
||||
"is_self": false,
|
||||
"leader_address": "https://127.0.0.1:8200/"
|
||||
}
|
||||
```
|
||||
|
||||
</dd>
|
||||
</dl>
|
||||
|
|
@ -1,203 +0,0 @@
|
|||
---
|
||||
layout: "http"
|
||||
page_title: "HTTP API: /sys/mounts"
|
||||
sidebar_current: "docs-http-mounts-mounts"
|
||||
description: |-
|
||||
The '/sys/mounts' endpoint is used manage secret backends in Vault.
|
||||
---
|
||||
|
||||
# /sys/mounts
|
||||
|
||||
## GET
|
||||
|
||||
<dl>
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Lists all the mounted secret backends. `default_lease_ttl`
|
||||
or `max_lease_ttl` values of `0` mean that the system
|
||||
defaults are used by this backend.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>GET</dd>
|
||||
|
||||
<dt>URL</dt>
|
||||
<dd>`/sys/mounts`</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>
|
||||
None
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>
|
||||
|
||||
```javascript
|
||||
{
|
||||
"aws": {
|
||||
"type": "aws",
|
||||
"description": "AWS keys",
|
||||
"config": {
|
||||
"default_lease_ttl": 0,
|
||||
"max_lease_ttl": 0,
|
||||
"force_no_cache": false
|
||||
}
|
||||
},
|
||||
|
||||
"sys": {
|
||||
"type": "system",
|
||||
"description": "system endpoint",
|
||||
"config": {
|
||||
"default_lease_ttl": 0,
|
||||
"max_lease_ttl": 0,
|
||||
"force_no_cache": false
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
## POST
|
||||
|
||||
<dl>
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Mount a new secret backend to the mount point in the URL.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>POST</dd>
|
||||
|
||||
<dt>URL</dt>
|
||||
<dd>`/sys/mounts/<mount point>`</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>
|
||||
<ul>
|
||||
<li>
|
||||
<span class="param">type</span>
|
||||
<span class="param-flags">required</span>
|
||||
The name of the backend type, such as "aws"
|
||||
</li>
|
||||
<li>
|
||||
<span class="param">description</span>
|
||||
<span class="param-flags">optional</span>
|
||||
A human-friendly description of the mount.
|
||||
</li>
|
||||
<li>
|
||||
<span class="param">config</span>
|
||||
<span class="param-flags">optional</span>
|
||||
Config options for this mount. This is an object with
|
||||
three possible values: `default_lease_ttl`,
|
||||
`max_lease_ttl`, and`force_no_cache`. These control the default and
|
||||
maximum lease time-to-live, and force disabling backend caching respectively.
|
||||
If set on a specific mount, this overrides the global defaults.
|
||||
</li>
|
||||
</ul>
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>`204` response code.
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
## DELETE
|
||||
|
||||
<dl>
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Unmount the mount point specified in the URL.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>DELETE</dd>
|
||||
|
||||
<dt>URL</dt>
|
||||
<dd>`/sys/mounts/<mount point>`</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>None
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>`204` response code.
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
# /sys/mounts/[mount point]/tune
|
||||
|
||||
## GET
|
||||
|
||||
<dl>
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Read the given mount's configuration. Unlike the `mounts`
|
||||
endpoint, this will return the current time in seconds for each
|
||||
TTL, which may be the system default or a mount-specific value.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>GET</dd>
|
||||
|
||||
<dt>URL</dt>
|
||||
<dd>`/sys/mounts/<mount point>/tune`</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>
|
||||
None
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>
|
||||
|
||||
```javascript
|
||||
{
|
||||
"default_lease_ttl": 3600,
|
||||
"max_lease_ttl": 7200,
|
||||
"force_no_cache": false
|
||||
}
|
||||
```
|
||||
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
## POST
|
||||
|
||||
<dl>
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Tune configuration parameters for a given mount point.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>POST</dd>
|
||||
|
||||
<dt>URL</dt>
|
||||
<dd>`/sys/mounts/<mount point>/tune`</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>
|
||||
<ul>
|
||||
<li>
|
||||
<span class="param">default_lease_ttl</span>
|
||||
<span class="param-flags">optional</span>
|
||||
The default time-to-live. If set on a specific mount,
|
||||
overrides the global default. A value of "system" or "0"
|
||||
are equivalent and set to the system default TTL.
|
||||
</li>
|
||||
<li>
|
||||
<span class="param">max_lease_ttl</span>
|
||||
<span class="param-flags">optional</span>
|
||||
The maximum time-to-live. If set on a specific mount,
|
||||
overrides the global default. A value of "system" or "0"
|
||||
are equivalent and set to the system max TTL.
|
||||
</li>
|
||||
</ul>
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>`204` response code.
|
||||
</dd>
|
||||
</dl>
|
||||
|
|
@ -1,126 +0,0 @@
|
|||
---
|
||||
layout: "http"
|
||||
page_title: "HTTP API: /sys/policy"
|
||||
sidebar_current: "docs-http-auth-policy"
|
||||
description: |-
|
||||
The `/sys/policy` endpoint is used to manage ACL policies in Vault.
|
||||
---
|
||||
|
||||
# /sys/policy
|
||||
|
||||
## GET
|
||||
|
||||
<dl>
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Lists all the available policies.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>GET</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>
|
||||
None
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>
|
||||
|
||||
```javascript
|
||||
{
|
||||
"policies": ["root", "deploy"]
|
||||
}
|
||||
```
|
||||
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
# /sys/policy/
|
||||
|
||||
## GET
|
||||
|
||||
<dl>
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Retrieve the rules for the named policy.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>GET</dd>
|
||||
|
||||
<dt>URL</dt>
|
||||
<dd>`/sys/policy/<name>`</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>
|
||||
None
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>
|
||||
|
||||
```javascript
|
||||
{
|
||||
"rules": "path..."
|
||||
}
|
||||
```
|
||||
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
|
||||
## PUT
|
||||
|
||||
<dl>
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Add or update a policy. Once a policy is updated, it takes effect
|
||||
immediately to all associated users.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>PUT</dd>
|
||||
|
||||
<dt>URL</dt>
|
||||
<dd>`/sys/policy/<name>`</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>
|
||||
<ul>
|
||||
<li>
|
||||
<span class="param">rules</span>
|
||||
<span class="param-flags">required</span>
|
||||
The policy document.
|
||||
</li>
|
||||
</ul>
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>`204` response code.
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
## DELETE
|
||||
|
||||
<dl>
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Delete the policy with the given name. This will immediately
|
||||
affect all associated users.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>DELETE</dd>
|
||||
|
||||
<dt>URL</dt>
|
||||
<dd>`/sys/policy/<name>`</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>None
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>`204` response code.
|
||||
</dd>
|
||||
</dl>
|
||||
|
|
@ -1,96 +0,0 @@
|
|||
---
|
||||
layout: "http"
|
||||
page_title: "HTTP API: /sys/raw"
|
||||
sidebar_current: "docs-http-debug-raw"
|
||||
description: |-
|
||||
The `/sys/raw` endpoint is access the raw underlying store in Vault.
|
||||
---
|
||||
|
||||
# /sys/raw
|
||||
|
||||
## GET
|
||||
|
||||
<dl>
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Reads the value of the key at the given path. This is the raw path in the
|
||||
storage backend and not the logical path that is exposed via the mount system.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>GET</dd>
|
||||
|
||||
<dt>URL</dt>
|
||||
<dd>`/sys/raw/<path>`</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>
|
||||
None
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>
|
||||
|
||||
```javascript
|
||||
{
|
||||
"value": "{'foo':'bar'}"
|
||||
}
|
||||
```
|
||||
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
## PUT
|
||||
|
||||
<dl>
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Update the value of the key at the given path. This is the raw path in the
|
||||
storage backend and not the logical path that is exposed via the mount system.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>PUT</dd>
|
||||
|
||||
<dt>URL</dt>
|
||||
<dd>`/sys/raw/<path>`</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>
|
||||
<ul>
|
||||
<li>
|
||||
<span class="param">value</span>
|
||||
<span class="param-flags">required</span>
|
||||
The value of the key.
|
||||
</li>
|
||||
</ul>
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>`204` response code.
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
## DELETE
|
||||
|
||||
<dl>
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Delete the key with given path. This is the raw path in the
|
||||
storage backend and not the logical path that is exposed via the mount system.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>DELETE</dd>
|
||||
|
||||
<dt>URL</dt>
|
||||
<dd>`/sys/raw/<path>`</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>None
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>`204` response code.
|
||||
</dd>
|
||||
</dl>
|
||||
|
|
@ -1,251 +0,0 @@
|
|||
---
|
||||
layout: "http"
|
||||
page_title: "HTTP API: /sys/rekey/"
|
||||
sidebar_current: "docs-http-rotate-rekey"
|
||||
description: |-
|
||||
The `/sys/rekey/` endpoints are used to rekey the unseal keys for Vault.
|
||||
---
|
||||
|
||||
# /sys/rekey/init
|
||||
|
||||
## GET
|
||||
|
||||
<dl>
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Reads the configuration and progress of the current rekey attempt.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>GET</dd>
|
||||
|
||||
<dt>URL</dt>
|
||||
<dd>`/sys/rekey/init`</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>
|
||||
None
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>
|
||||
If a rekey is started, then `n` is the new shares to generate and `t` is
|
||||
the threshold required for the new shares. `progress` is how many unseal
|
||||
keys have been provided for this rekey, where `required` must be reached to
|
||||
complete. The `nonce` for the current rekey operation is also displayed. If
|
||||
PGP keys are being used to encrypt the final shares, the key fingerprints
|
||||
and whether the final keys will be backed up to physical storage will also
|
||||
be displayed.
|
||||
|
||||
```javascript
|
||||
{
|
||||
"started": true,
|
||||
"nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63",
|
||||
"t": 3,
|
||||
"n": 5,
|
||||
"progress": 1,
|
||||
"required": 3,
|
||||
"pgp_fingerprints": ["abcd1234"],
|
||||
"backup": true
|
||||
}
|
||||
```
|
||||
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
## PUT
|
||||
|
||||
<dl>
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Initializes a new rekey attempt. Only a single rekey attempt can take place
|
||||
at a time, and changing the parameters of a rekey requires canceling and
|
||||
starting a new rekey, which will also provide a new nonce.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>PUT</dd>
|
||||
|
||||
<dt>URL</dt>
|
||||
<dd>`/sys/rekey/init`</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>
|
||||
<ul>
|
||||
<li>
|
||||
<span class="param">secret_shares</span>
|
||||
<span class="param-flags">required</span>
|
||||
The number of shares to split the master key into.
|
||||
</li>
|
||||
<li>
|
||||
<span class="param">secret_threshold</span>
|
||||
<span class="param-flags">required</span>
|
||||
The number of shares required to reconstruct the master key.
|
||||
This must be less than or equal to <code>secret_shares</code>.
|
||||
</li>
|
||||
<li>
|
||||
<spam class="param">pgp_keys</span>
|
||||
<span class="param-flags">optional</spam>
|
||||
An array of PGP public keys used to encrypt the output unseal keys.
|
||||
Ordering is preserved. The keys must be base64-encoded from their
|
||||
original binary representation. The size of this array must be the
|
||||
same as <code>secret_shares</code>.
|
||||
</li>
|
||||
<li>
|
||||
<spam class="param">backup</span>
|
||||
<span class="param-flags">optional</spam>
|
||||
If using PGP-encrypted keys, whether Vault should also back them up to
|
||||
a well-known location in physical storage (`core/unseal-keys-backup`).
|
||||
These can then be retrieved and removed via the `sys/rekey/backup`
|
||||
endpoint.
|
||||
</li>
|
||||
</ul>
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>`204` response code.
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
## DELETE
|
||||
|
||||
<dl>
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Cancels any in-progress rekey. This clears the rekey settings as well as any
|
||||
progress made. This must be called to change the parameters of the rekey.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>DELETE</dd>
|
||||
|
||||
<dt>URL</dt>
|
||||
<dd>`/sys/rekey/init`</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>None
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>`204` response code.
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
# /sys/rekey/backup
|
||||
|
||||
## GET
|
||||
|
||||
<dl>
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Return the backup copy of PGP-encrypted unseal keys. The returned value is
|
||||
the nonce of the rekey operation and a map of PGP key fingerprint to
|
||||
hex-encoded PGP-encrypted key.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>GET</dd>
|
||||
|
||||
<dt>URL</dt>
|
||||
<dd>`/sys/rekey/backup`</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>
|
||||
None
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>
|
||||
|
||||
```javascript
|
||||
{
|
||||
"nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63",
|
||||
"keys": {
|
||||
"abcd1234": "..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
## DELETE
|
||||
|
||||
<dl>
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Delete the backup copy of PGP-encrypted unseal keys.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>DELETE</dd>
|
||||
|
||||
<dt>URL</dt>
|
||||
<dd>`/sys/rekey/backup`</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>None
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>`204` response code.
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
# /sys/rekey/update
|
||||
|
||||
## PUT
|
||||
|
||||
<dl>
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Enter a single master key share to progress the rekey of the Vault.
|
||||
If the threshold number of master key shares is reached, Vault
|
||||
will complete the rekey. Otherwise, this API must be called multiple
|
||||
times until that threshold is met. The rekey nonce operation must be
|
||||
provided with each call.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>PUT</dd>
|
||||
|
||||
<dt>URL</dt>
|
||||
<dd>`/sys/rekey/update`</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>
|
||||
<ul>
|
||||
<li>
|
||||
<span class="param">key</span>
|
||||
<span class="param-flags">required</span>
|
||||
A single master share key.
|
||||
</li>
|
||||
<li>
|
||||
<span class="param">nonce</span>
|
||||
<span class="param-flags">required</span>
|
||||
The nonce of the rekey operation.
|
||||
</li>
|
||||
</ul>
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>
|
||||
A JSON-encoded object indicating the rekey operation nonce and completion
|
||||
status; if completed, the new master keys are returned. If the keys are
|
||||
PGP-encrypted, an array of key fingerprints will also be provided (with the
|
||||
order in which the keys were used for encryption) along with whether or not
|
||||
the keys were backed up to physical storage:
|
||||
|
||||
```javascript
|
||||
{
|
||||
"complete": true,
|
||||
"keys": ["one", "two", "three"],
|
||||
"nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63",
|
||||
"pgp_fingerprints": ["abcd1234"],
|
||||
"keys_base64": ["base64keyvalue"],
|
||||
"backup": true
|
||||
}
|
||||
```
|
||||
|
||||
</dd>
|
||||
</dl>
|
||||
|
|
@ -1,39 +0,0 @@
|
|||
---
|
||||
layout: "http"
|
||||
page_title: "HTTP API: /sys/remount"
|
||||
sidebar_current: "docs-http-mounts-remount"
|
||||
description: |-
|
||||
The '/sys/remount' endpoint is used remount a mounted backend to a new endpoint.
|
||||
---
|
||||
|
||||
# /sys/remount
|
||||
|
||||
<dl>
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Remount an already-mounted backend to a new mount point.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>POST</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>
|
||||
<ul>
|
||||
<li>
|
||||
<span class="param">from</span>
|
||||
<span class="param-flags">required</span>
|
||||
The previous mount point.
|
||||
</li>
|
||||
<li>
|
||||
<span class="param">to</span>
|
||||
<span class="param-flags">required</span>
|
||||
The new mount point.
|
||||
</li>
|
||||
</ul>
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>`204` response code.
|
||||
</dd>
|
||||
</dl>
|
||||
|
|
@ -1,44 +0,0 @@
|
|||
---
|
||||
layout: "http"
|
||||
page_title: "HTTP API: /sys/renew"
|
||||
sidebar_current: "docs-http-lease-renew"
|
||||
description: |-
|
||||
The `/sys/renew` endpoint is used to renew secrets.
|
||||
---
|
||||
|
||||
# /sys/renew
|
||||
|
||||
<dl>
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Renew a secret, requesting to extend the lease.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>PUT</dd>
|
||||
|
||||
<dt>URL</dt>
|
||||
<dd>`/sys/renew(/<lease id>)`</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>
|
||||
<ul>
|
||||
<li>
|
||||
<span class="param">increment</span>
|
||||
<span class="param-flags">optional</span>
|
||||
A requested amount of time in seconds to extend the lease.
|
||||
This is advisory.
|
||||
</li>
|
||||
<li>
|
||||
<span class="param">lease_id</span>
|
||||
<span class="param-flags">required</span>
|
||||
The ID of the lease to extend. This can be specified as part of the URL
|
||||
or in the request body.
|
||||
</li>
|
||||
</ul>
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>A secret structure.
|
||||
</dd>
|
||||
</dl>
|
||||
|
|
@ -1,36 +0,0 @@
|
|||
---
|
||||
layout: "http"
|
||||
page_title: "HTTP API: /sys/revoke-force"
|
||||
sidebar_current: "docs-http-lease-revoke-force"
|
||||
description: |-
|
||||
The `/sys/revoke-force` endpoint is used to revoke secrets or tokens based on prefix while ignoring backend errors.
|
||||
---
|
||||
|
||||
# /sys/revoke-force
|
||||
|
||||
<dl>
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Revoke all secrets or tokens generated under a given prefix immediately.
|
||||
Unlike `/sys/revoke-prefix`, this path ignores backend errors encountered
|
||||
during revocation. This is <i>potentially very dangerous</i> and should
|
||||
only be used in specific emergency situations where errors in the backend
|
||||
or the connected backend service prevent normal revocation. <i>By ignoring
|
||||
these errors, Vault abdicates responsibility for ensuring that the issued
|
||||
credentials or secrets are properly revoked and/or cleaned up. Access to
|
||||
this endpoint should be tightly controlled.</i>
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>PUT</dd>
|
||||
|
||||
<dt>URL</dt>
|
||||
<dd>`/sys/revoke-force/<path prefix>`</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>None</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>A `204` response code.
|
||||
</dd>
|
||||
</dl>
|
||||
|
|
@ -1,32 +0,0 @@
|
|||
---
|
||||
layout: "http"
|
||||
page_title: "HTTP API: /sys/revoke-prefix"
|
||||
sidebar_current: "docs-http-lease-revoke-prefix"
|
||||
description: |-
|
||||
The `/sys/revoke-prefix` endpoint is used to revoke secrets or tokens based on prefix.
|
||||
---
|
||||
|
||||
# /sys/revoke-prefix
|
||||
|
||||
<dl>
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Revoke all secrets (via a lease ID prefix) or tokens (via the tokens' path
|
||||
property) generated under a given prefix immediately. This requires `sudo`
|
||||
capability and access to it should be tightly controlled as it can be used
|
||||
to revoke very large numbers of secrets/tokens at once.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>PUT</dd>
|
||||
|
||||
<dt>URL</dt>
|
||||
<dd>`/sys/revoke-prefix/<path prefix>`</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>None</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>A `204` response code.
|
||||
</dd>
|
||||
</dl>
|
||||
|
|
@ -1,29 +0,0 @@
|
|||
---
|
||||
layout: "http"
|
||||
page_title: "HTTP API: /sys/revoke"
|
||||
sidebar_current: "docs-http-lease-revoke-single"
|
||||
description: |-
|
||||
The `/sys/revoke` endpoint is used to revoke secrets.
|
||||
---
|
||||
|
||||
# /sys/revoke
|
||||
|
||||
<dl>
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Revoke a secret immediately.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>PUT</dd>
|
||||
|
||||
<dt>URL</dt>
|
||||
<dd>`/sys/revoke/<lease id>`</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>None</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>A `204` response code.
|
||||
</dd>
|
||||
</dl>
|
||||
|
|
@ -1,37 +0,0 @@
|
|||
---
|
||||
layout: "http"
|
||||
page_title: "HTTP API: /sys/rotate"
|
||||
sidebar_current: "docs-http-rotate-rotate"
|
||||
description: |-
|
||||
The `/sys/rotate` endpoint is used to rotate the encryption key.
|
||||
---
|
||||
|
||||
# /sys/rotate
|
||||
|
||||
## PUT
|
||||
|
||||
<dl>
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Trigger a rotation of the backend encryption key. This is the key that is used
|
||||
to encrypt data written to the storage backend, and is not provided to operators.
|
||||
This operation is done online. Future values are encrypted with the new key, while
|
||||
old values are decrypted with previous encryption keys.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>PUT</dd>
|
||||
|
||||
<dt>URL</dt>
|
||||
<dd>`/sys/rotate`</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>
|
||||
None
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>`204` response code.
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
|
|
@ -1,54 +0,0 @@
|
|||
---
|
||||
layout: "http"
|
||||
page_title: "HTTP API: /sys/seal-status"
|
||||
sidebar_current: "docs-http-seal-status"
|
||||
description: |-
|
||||
The '/sys/seal-status' endpoint is used to check the seal status of a Vault.
|
||||
---
|
||||
|
||||
# /sys/seal-status
|
||||
|
||||
<dl>
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Returns the seal status of the Vault.<br/><br/>This is an unauthenticated endpoint.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>GET</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>
|
||||
None
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>
|
||||
The "t" parameter is the threshold, and "n" is the number of shares.
|
||||
|
||||
```javascript
|
||||
{
|
||||
"sealed": true,
|
||||
"t": 3,
|
||||
"n": 5,
|
||||
"progress": 2,
|
||||
"version": "0.6.1-dev"
|
||||
}
|
||||
```
|
||||
|
||||
Sample response when Vault is unsealed.
|
||||
|
||||
```javascript
|
||||
{
|
||||
"sealed": false,
|
||||
"t": 3,
|
||||
"n": 5,
|
||||
"progress": 0,
|
||||
"version": "0.6.1-dev",
|
||||
"cluster_name": "vault-cluster-d6ec3c7f",
|
||||
"cluster_id": "3e8b3fec-3749-e056-ba41-b62a63b997e8"
|
||||
}
|
||||
```
|
||||
|
||||
</dd>
|
||||
</dl>
|
||||
|
|
@ -1,30 +0,0 @@
|
|||
---
|
||||
layout: "http"
|
||||
page_title: "HTTP API: /sys/seal"
|
||||
sidebar_current: "docs-http-seal-seal"
|
||||
description: |-
|
||||
The '/sys/seal' endpoint seals the Vault.
|
||||
---
|
||||
|
||||
# /sys/seal
|
||||
|
||||
<dl>
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Seals the Vault. In HA mode, only an active node can be sealed. Standby
|
||||
nodes should be restarted to get the same effect. Requires a token with
|
||||
`root` policy or `sudo` capability on the path.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>PUT</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>
|
||||
None
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>A `204` response code.
|
||||
</dd>
|
||||
</dl>
|
||||
|
|
@ -1,33 +0,0 @@
|
|||
---
|
||||
layout: "http"
|
||||
page_title: "HTTP API: /sys/step-down"
|
||||
sidebar_current: "docs-http-ha-step-down"
|
||||
description: |-
|
||||
The '/sys/step-down' endpoint causes the node to give up active status.
|
||||
---
|
||||
|
||||
# /sys/step-down
|
||||
|
||||
<dl>
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Forces the node to give up active status. If the node does not have active
|
||||
status, this endpoint does nothing. Note that the node will sleep for ten
|
||||
seconds before attempting to grab the active lock again, but if no standby
|
||||
nodes grab the active lock in the interim, the same node may become the
|
||||
active node again. Requires a token with `root` policy or `sudo` capability
|
||||
on the path.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>PUT</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>
|
||||
None
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>A `204` response code.
|
||||
</dd>
|
||||
</dl>
|
||||
|
|
@ -1,44 +0,0 @@
|
|||
---
|
||||
layout: "http"
|
||||
page_title: "HTTP API: /sys/seal-unseal"
|
||||
sidebar_current: "docs-http-seal-unseal"
|
||||
description: |-
|
||||
The '/sys/seal-unseal' endpoint is used to unseal the Vault.
|
||||
---
|
||||
|
||||
# /sys/unseal
|
||||
|
||||
<dl>
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Enter a single master key share to progress the unsealing of the Vault.
|
||||
If the threshold number of master key shares is reached, Vault
|
||||
will attempt to unseal the Vault. Otherwise, this API must be
|
||||
called multiple times until that threshold is met.<br/><br/>Either
|
||||
the `key` or `reset` parameter must be provided; if both are provided,
|
||||
`reset` takes precedence.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>PUT</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>
|
||||
<ul>
|
||||
<li>
|
||||
<span class="param">key</span>
|
||||
<span class="param-flags">optional</span>
|
||||
A single master share key.
|
||||
</li>
|
||||
<li>
|
||||
<span class="param">reset</span>
|
||||
<span class="param-flags">optional</span>
|
||||
A boolean; if true, the previously-provided unseal keys are discarded
|
||||
from memory and the unseal process is reset.
|
||||
</li>
|
||||
</ul>
|
||||
</dd>
|
||||
<dt>Returns</dt>
|
||||
<dd>The same result as `/sys/seal-status`.
|
||||
</dd>
|
||||
</dl>
|
||||
|
|
@ -1,54 +0,0 @@
|
|||
---
|
||||
layout: "http"
|
||||
page_title: "HTTP API: /sys/wrapping/lookup"
|
||||
sidebar_current: "docs-http-wrapping-lookup"
|
||||
description: |-
|
||||
The '/sys/wrapping/lookup' endpoint returns wrapping token properties
|
||||
---
|
||||
|
||||
# /sys/wrapping/lookup
|
||||
|
||||
## POST
|
||||
|
||||
<dl>
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Looks up wrapping properties for the given token.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>POST</dd>
|
||||
|
||||
<dt>URL</dt>
|
||||
<dd>`/sys/wrapping/lookup`</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>
|
||||
<ul>
|
||||
<li>
|
||||
<span class="param">token</span>
|
||||
<span class="param-flags">required</span>
|
||||
The wrapping token ID.
|
||||
</li>
|
||||
</ul>
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>
|
||||
|
||||
```javascript
|
||||
{
|
||||
"request_id": "481320f5-fdf8-885d-8050-65fa767fd19b",
|
||||
"lease_id": "",
|
||||
"lease_duration": 0,
|
||||
"renewable": false,
|
||||
"data": {
|
||||
"creation_time": "2016-09-28T14:16:13.07103516-04:00",
|
||||
"creation_ttl": 300
|
||||
},
|
||||
"warnings": null
|
||||
}
|
||||
```
|
||||
|
||||
</dd>
|
||||
</dl>
|
||||
|
|
@ -1,60 +0,0 @@
|
|||
---
|
||||
layout: "http"
|
||||
page_title: "HTTP API: /sys/wrapping/rewrap"
|
||||
sidebar_current: "docs-http-wrapping-rewrap"
|
||||
description: |-
|
||||
The '/sys/wrapping/rewrap' endpoint can be used to rotate a wrapping token and refresh its TTL
|
||||
---
|
||||
|
||||
# /sys/wrapping/rewrap
|
||||
|
||||
## POST
|
||||
|
||||
<dl>
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Rewraps a response-wrapped token; the new token will use the same creation
|
||||
TTL as the original token and contain the same response. The old token will
|
||||
be invalidated. This can be used for long-term storage of a secret in a
|
||||
response-wrapped token when rotation is a requirement.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>POST</dd>
|
||||
|
||||
<dt>URL</dt>
|
||||
<dd>`/sys/wrapping/rewrap`</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>
|
||||
<ul>
|
||||
<li>
|
||||
<span class="param">token</span>
|
||||
<span class="param-flags">required</span>
|
||||
The wrapping token ID.
|
||||
</li>
|
||||
</ul>
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>
|
||||
|
||||
```javascript
|
||||
{
|
||||
"request_id": "",
|
||||
"lease_id": "",
|
||||
"lease_duration": 0,
|
||||
"renewable": false,
|
||||
"data": null,
|
||||
"warnings": null,
|
||||
"wrap_info": {
|
||||
"token": "3b6f1193-0707-ac17-284d-e41032e74d1f",
|
||||
"ttl": 300,
|
||||
"creation_time": "2016-09-28T14:22:26.486186607-04:00",
|
||||
"wrapped_accessor": ""
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</dd>
|
||||
</dl>
|
||||
|
|
@ -1,65 +0,0 @@
|
|||
---
|
||||
layout: "http"
|
||||
page_title: "HTTP API: /sys/wrapping/unwrap"
|
||||
sidebar_current: "docs-http-wrapping-unwrap"
|
||||
description: |-
|
||||
The '/sys/wrapping/unwrap' endpoint unwraps a wrapped response
|
||||
---
|
||||
|
||||
# /sys/wrapping/unwrap
|
||||
|
||||
## POST
|
||||
|
||||
<dl>
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Returns the original response inside the given wrapping token. Unlike
|
||||
simply reading `cubbyhole/response` (which is deprecated), this endpoint
|
||||
provides additional validation checks on the token, returns the original
|
||||
value on the wire rather than a JSON string representation of it, and
|
||||
ensures that the response is properly audit-logged.<br/><br/>This endpoint
|
||||
can be used by using a wrapping token as the client token in the API call,
|
||||
in which case the `token` parameter is not required; or, a different token
|
||||
with permissions to access this endpoint can make the call and pass in the
|
||||
wrapping token in the `token` parameter. Do _not_ use the wrapping token in
|
||||
both locations; this will cause the wrapping token to be revoked but the
|
||||
value to be unable to be looked up, as it will basically be a double-use of
|
||||
the token!
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>POST</dd>
|
||||
|
||||
<dt>URL</dt>
|
||||
<dd>`/sys/wrapping/unwrap`</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>
|
||||
<ul>
|
||||
<li>
|
||||
<span class="param">token</span>
|
||||
<span class="param-flags">optional</span>
|
||||
The wrapping token ID; required if the client token is not the wrapping
|
||||
token. Do not use the wrapping token in both locations.
|
||||
</li>
|
||||
</ul>
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>
|
||||
|
||||
```javascript
|
||||
{
|
||||
"request_id": "8e33c808-f86c-cff8-f30a-fbb3ac22c4a8",
|
||||
"lease_id": "",
|
||||
"lease_duration": 2592000,
|
||||
"renewable": false,
|
||||
"data": {
|
||||
"zip": "zap"
|
||||
},
|
||||
"warnings": null
|
||||
}
|
||||
```
|
||||
|
||||
</dd>
|
||||
</dl>
|
||||
|
|
@ -1,59 +0,0 @@
|
|||
---
|
||||
layout: "http"
|
||||
page_title: "HTTP API: /sys/wrapping/wrap"
|
||||
sidebar_current: "docs-http-wrapping-wrap"
|
||||
description: |-
|
||||
The '/sys/wrapping/wrap' endpoint wraps the given values in a response-wrapped token
|
||||
---
|
||||
|
||||
# /sys/wrapping/wrap
|
||||
|
||||
## POST
|
||||
|
||||
<dl>
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Wraps the given user-supplied data inside a response-wrapped token.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>POST</dd>
|
||||
|
||||
<dt>URL</dt>
|
||||
<dd>`/sys/wrapping/wrap`</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>
|
||||
<ul>
|
||||
<li>
|
||||
<span class="param">[any]</span>
|
||||
<span class="param-flags">optional</span>
|
||||
Parameters should be supplied as keys/values in a JSON object. The
|
||||
exact set of given parameters will be contained in the wrapped
|
||||
response.
|
||||
</li>
|
||||
</ul>
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>
|
||||
|
||||
```javascript
|
||||
{
|
||||
"request_id": "",
|
||||
"lease_id": "",
|
||||
"lease_duration": 0,
|
||||
"renewable": false,
|
||||
"data": null,
|
||||
"warnings": null,
|
||||
"wrap_info": {
|
||||
"token": "fb79b9d3-d94e-9eb6-4919-c559311133d6",
|
||||
"ttl": 300,
|
||||
"creation_time": "2016-09-28T14:41:00.56961496-04:00",
|
||||
"wrapped_accessor": ""
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</dd>
|
||||
</dl>
|
||||
63
website/source/docs/http/system/audit-hash.html.md
Normal file
63
website/source/docs/http/system/audit-hash.html.md
Normal file
|
|
@ -0,0 +1,63 @@
|
|||
---
|
||||
layout: "http"
|
||||
page_title: /sys/audit-hash - HTTP API"
|
||||
sidebar_current: "docs-http-system-audit-hash"
|
||||
description: |-
|
||||
The `/sys/audit-hash` endpoint is used to hash data using an audit backend's
|
||||
hash function and salt.
|
||||
---
|
||||
|
||||
# `/sys/audit-hash`
|
||||
|
||||
The `/sys/audit-hash` endpoint is used to calculate the hash of the data used by
|
||||
an audit backend's hash function and salt. This can be used to search audit logs
|
||||
for a hashed value when the original value is known.
|
||||
|
||||
## Calculate Hash
|
||||
|
||||
This endpoint hashes the given input data with the specified audit backend's
|
||||
hash function and salt. This endpoint can be used to discover whether a given
|
||||
plaintext string (the `input` parameter) appears in the audit log in obfuscated
|
||||
form.
|
||||
|
||||
The audit log records requests and responses. Since the Vault API is JSON-based,
|
||||
any binary data returned from an API call (such as a DER-format certificate) is
|
||||
base64-encoded by the Vault server in the response. As a result such information
|
||||
should also be base64-encoded to supply into the `input` parameter.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :---------------------- | :--------------------- |
|
||||
| `POST` | `/sys/audit-hash/:path` | `204 (empty body)` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `path` `(string: <required>)` – Specifies the path of the audit backend to
|
||||
generate hashes for. This is part of the request URL.
|
||||
|
||||
- `input` `(string: <required>)` – Specifies the input string to hash.
|
||||
|
||||
### Sample Payload
|
||||
|
||||
```json
|
||||
{
|
||||
"input": "my-secret-vault"
|
||||
}
|
||||
```
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request POST \
|
||||
--data @payload.json \
|
||||
https://vault.rocks/v1/sys/audit-hash/example-audit
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"hash": "hmac-sha256:08ba35..."
|
||||
}
|
||||
```
|
||||
118
website/source/docs/http/system/audit.html.md
Normal file
118
website/source/docs/http/system/audit.html.md
Normal file
|
|
@ -0,0 +1,118 @@
|
|||
---
|
||||
layout: "http"
|
||||
page_title: "/sys/audit - HTTP API"
|
||||
sidebar_current: "docs-http-system-audit/"
|
||||
description: |-
|
||||
The `/sys/audit` endpoint is used to enable and disable audit backends.
|
||||
---
|
||||
|
||||
# `/sys/audit`
|
||||
|
||||
The `/sys/audit` endpoint is used to list, mount, and unmount audit backends.
|
||||
Audit backends must be enabled before use, and more than one backend may be
|
||||
enabled at a time.
|
||||
|
||||
## List Mounted Audit Backends
|
||||
|
||||
This endpoint lists only the mounted audit backends (it does not list all
|
||||
available audit backends).
|
||||
|
||||
- **`sudo` required** – This endpoint requires `sudo` capability in addition to
|
||||
any path-specific capabilities.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `GET` | `/sys/audit` | `200 application/json` |
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
https://vault.rocks/v1/sys/audit
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```javascript
|
||||
{
|
||||
"file": {
|
||||
"type": "file",
|
||||
"description": "Store logs in a file",
|
||||
"options": {
|
||||
"path": "/var/log/vault.log"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Mount Audit Backend
|
||||
|
||||
This endpoint mounts a new audit backend at the supplied path. The path can be a
|
||||
single word name or a more complex, nested path.
|
||||
|
||||
- **`sudo` required** – This endpoint requires `sudo` capability in addition to
|
||||
any path-specific capabilities.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `PUT` | `/sys/audit/:path` | `204 (empty body)` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `path` `(string: <required>)` – Specifies the path in which to mount the audit
|
||||
backend. This is part of the request URL.
|
||||
|
||||
- `description` `(string: "")` – Specifies a human-friendly description of the
|
||||
audit backend.
|
||||
|
||||
- `options` `(map<string|string>: nil)` – Specifies configuration options to
|
||||
pass to the audit backend itself. This is dependent on the audit backend type.
|
||||
|
||||
- `type` `(string: <required>)` – Specifies the type of the audit backend.
|
||||
|
||||
### Sample Payload
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "file",
|
||||
"options": {
|
||||
"path": "/var/log/vault/log"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request PUT \
|
||||
--data @payload.json \
|
||||
https://vault.rocks/v1/sys/audit/example-audit
|
||||
```
|
||||
|
||||
## Unmount Audit Backend
|
||||
|
||||
This endpoint un-mounts the audit backend at the given path.
|
||||
|
||||
- **`sudo` required** – This endpoint requires `sudo` capability in addition to
|
||||
any path-specific capabilities.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `DELETE` | `/sys/audit/:path` | `204 (empty body)` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `path` `(string: <required>)` – Specifies the path of the audit backend to
|
||||
delete. This is part of the request URL.
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request DELETE \
|
||||
https://vault.rocks/v1/sys/audit/example-audit
|
||||
```
|
||||
193
website/source/docs/http/system/auth.html.md
Normal file
193
website/source/docs/http/system/auth.html.md
Normal file
|
|
@ -0,0 +1,193 @@
|
|||
---
|
||||
layout: "http"
|
||||
page_title: "/sys/auth - HTTP API"
|
||||
sidebar_current: "docs-http-system-auth"
|
||||
description: |-
|
||||
The `/sys/auth` endpoint is used to manage auth backends in Vault.
|
||||
---
|
||||
|
||||
# `/sys/auth`
|
||||
|
||||
The `/sys/auth` endpoint is used to list, create, update, and delete auth
|
||||
backends. Auth backends convert user or machine-supplied information into a
|
||||
token which can be used for all future requests.
|
||||
|
||||
## List Auth Backends
|
||||
|
||||
This endpoint lists all enabled auth backends.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `GET` | `/sys/auth` | `200 application/json` |
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
https://vault.rocks/v1/sys/auth
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"github/": {
|
||||
"type": "github",
|
||||
"description": "GitHub auth"
|
||||
},
|
||||
"token/": {
|
||||
"config": {
|
||||
"default_lease_ttl": 0,
|
||||
"max_lease_ttl": 0
|
||||
},
|
||||
"description": "token based credentials",
|
||||
"type": "token"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Mount Auth Backend
|
||||
|
||||
This endpoint enables a new auth backend. After mounting, the auth backend can
|
||||
be accessed and configured via the auth path specified as part of the URL. This
|
||||
auth path will be nested under the `auth` prefix.
|
||||
|
||||
For example, mounting the "foo" auth backend will make it accessible at
|
||||
`/auth/foo`.
|
||||
|
||||
- **`sudo` required** – This endpoint requires `sudo` capability in addition to
|
||||
any path-specific capabilities.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `POST` | `/sys/auth/:path` | `204 (empty body)` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `path` `(string: <required>)` – Specifies the path in which to mount the auth
|
||||
backend. This is part of the request URL.
|
||||
|
||||
- `description` `(string: "")` – Specifies a human-friendly description of the
|
||||
auth backend.
|
||||
|
||||
- `type` `(string: <required>)` – Specifies the name of the authentication
|
||||
backend type, such as "github" or "token".
|
||||
|
||||
### Sample Payload
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "github",
|
||||
"description": "Login with GitHub"
|
||||
}
|
||||
```
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request POST \
|
||||
--data @payload.json \
|
||||
https://vault.rocks/v1/sys/auth/my-auth
|
||||
```
|
||||
|
||||
## Unmount Auth Backend
|
||||
|
||||
This endpoint un-mounts the auth backend at the given auth path.
|
||||
|
||||
- **`sudo` required** – This endpoint requires `sudo` capability in addition to
|
||||
any path-specific capabilities.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `DELETE` | `/sys/auth/:path` | `204 (empty body)` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `path` `(string: <required>)` – Specifies the path to unmount. This is part of
|
||||
the request URL.
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request DELETE \
|
||||
https://vault.rocks/v1/sys/auth/my-auth
|
||||
```
|
||||
|
||||
## Read Auth Backend Tuning
|
||||
|
||||
This endpoint reads the given auth path's configuration. _This endpoint requires
|
||||
`sudo` capability on the final path, but the same functionality can be achieved
|
||||
without `sudo` via `sys/mounts/auth/[auth-path]/tune`._
|
||||
|
||||
- **`sudo` required** – This endpoint requires `sudo` capability in addition to
|
||||
any path-specific capabilities.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `GET` | `/sys/auth/:path/tune` | `200 application/json` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `path` `(string: <required>)` – Specifies the path in which to tune.
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
https://vault.rocks/v1/sys/auth/my-auth/tune
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"default_lease_ttl": 3600,
|
||||
"max_lease_ttl": 7200
|
||||
}
|
||||
```
|
||||
|
||||
## Tune Auth Backend
|
||||
|
||||
Tune configuration parameters for a given auth path. _This endpoint
|
||||
requires `sudo` capability on the final path, but the same functionality
|
||||
can be achieved without `sudo` via `sys/mounts/auth/[auth-path]/tune`._
|
||||
|
||||
- **`sudo` required** – This endpoint requires `sudo` capability in addition to
|
||||
any path-specific capabilities.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `POST` | `/sys/auth/:path/tune` | `204 (empty body)` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `default_lease_ttl` `(int: 0)` – Specifies the default time-to-live. If set on
|
||||
a specific auth path, this overrides the global default.
|
||||
|
||||
- `max_lease_ttl` `(int: 0)` – Specifies the maximum time-to-live. If set on a
|
||||
specific auth path, this overrides the global default.
|
||||
|
||||
### Sample Payload
|
||||
|
||||
```json
|
||||
{
|
||||
"default_lease_ttl": 1800,
|
||||
"max_lease_ttl": 86400
|
||||
}
|
||||
```
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request POST \
|
||||
--data @payload.json \
|
||||
https://vault.rocks/v1/sys/auth/my-auth/tune
|
||||
```
|
||||
|
|
@ -0,0 +1,57 @@
|
|||
---
|
||||
layout: "http"
|
||||
page_title: "/sys/capabilities-accessor - HTTP API"
|
||||
sidebar_current: "docs-http-system-capabilities-accessor"
|
||||
description: |-
|
||||
The `/sys/capabilities-accessor` endpoint is used to fetch the capabilities of
|
||||
the token associated with an accessor, on the given path.
|
||||
---
|
||||
|
||||
# `/sys/capabilities-accessor`
|
||||
|
||||
The `/sys/capabilities-accessor` endpoint is used to fetch the capabilities of a
|
||||
token associated with an accessor.
|
||||
|
||||
## Query Token Accessor Capabilities
|
||||
|
||||
This endpoint returns the capabilities of the token associated with an accessor,
|
||||
for the given path.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `POST` | `/sys/capabilities-accessor` | `200 application/json` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `accessor` `(string: <required>)` – Specifies the accessor of the token to
|
||||
check.
|
||||
|
||||
- `path` `(string: <required>)` – Specifies the path on which the token's
|
||||
capabilities will be checked.
|
||||
|
||||
### Sample Payload
|
||||
|
||||
```json
|
||||
{
|
||||
"accessor": "abcd1234",
|
||||
"path": "secret/foo"
|
||||
}
|
||||
```
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request POST \
|
||||
--data payload.json \
|
||||
https://vault.rocks/v1/sys/capabilities-accessor
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"capabilities": ["read", "list"]
|
||||
}
|
||||
```
|
||||
54
website/source/docs/http/system/capabilities-self.html.md
Normal file
54
website/source/docs/http/system/capabilities-self.html.md
Normal file
|
|
@ -0,0 +1,54 @@
|
|||
---
|
||||
layout: "http"
|
||||
page_title: "/sys/capabilities-self - HTTP API"
|
||||
sidebar_current: "docs-http-system-capabilities-self"
|
||||
description: |-
|
||||
The `/sys/capabilities-self` endpoint is used to fetch the capabilities of
|
||||
client token on a given path.
|
||||
---
|
||||
|
||||
# `/sys/capabilities-self`
|
||||
|
||||
The `/sys/capabilities-self` endpoint is used to fetch the capabilities of a the
|
||||
supplied token.
|
||||
|
||||
## Query Self Capabilities
|
||||
|
||||
This endpoint returns the capabilities of client token on the given path. The
|
||||
client token is the Vault token with which this API call is made.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :----------------------- | :--------------------- |
|
||||
| `POST` | `/sys/capabilities-self` | `200 application/json` |
|
||||
|
||||
|
||||
### Parameters
|
||||
|
||||
- `path` `(string: <required>)` – Specifies the path on which the client token's
|
||||
capabilities will be checked.
|
||||
|
||||
### Sample Payload
|
||||
|
||||
```json
|
||||
{
|
||||
"path": "secret/foo"
|
||||
}
|
||||
```
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request POST \
|
||||
--data payload.json \
|
||||
https://vault.rocks/v1/sys/capabilities-self
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"capabilities": ["read", "list"]
|
||||
}
|
||||
```
|
||||
56
website/source/docs/http/system/capabilities.html.md
Normal file
56
website/source/docs/http/system/capabilities.html.md
Normal file
|
|
@ -0,0 +1,56 @@
|
|||
---
|
||||
layout: "http"
|
||||
page_title: "/sys/capabilities - HTTP API"
|
||||
sidebar_current: "docs-http-system-capabilities/"
|
||||
description: |-
|
||||
The `/sys/capabilities` endpoint is used to fetch the capabilities of a token
|
||||
on a given path.
|
||||
---
|
||||
|
||||
# `/sys/capabilities`
|
||||
|
||||
The `/sys/capabilities` endpoint is used to fetch the capabilities of a token on
|
||||
a given path.
|
||||
|
||||
## Query Token Capabilities
|
||||
|
||||
This endpoint returns the list of capabilities for a provided token.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :------------------- | :--------------------- |
|
||||
| `POST` | `/sys/capabilities` | `200 application/json` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `path` `(string: <required>)` – Specifies the path against which to check the
|
||||
token's capabilities.
|
||||
|
||||
- `token` `(string: <required>)` – Specifies the token for which to check
|
||||
capabilities.
|
||||
|
||||
### Sample Payload
|
||||
|
||||
```json
|
||||
{
|
||||
"path": "secret/foo",
|
||||
"token": "abcd1234"
|
||||
}
|
||||
```
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request POST \
|
||||
--data @payload.json \
|
||||
https://vault.rocks/v1/sys/capabilities
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"capabilities": ["read", "list"]
|
||||
}
|
||||
```
|
||||
130
website/source/docs/http/system/config-auditing.html.md
Normal file
130
website/source/docs/http/system/config-auditing.html.md
Normal file
|
|
@ -0,0 +1,130 @@
|
|||
---
|
||||
layout: "http"
|
||||
page_title: "/sys/config/auditing - HTTP API"
|
||||
sidebar_current: "docs-http-system-config-auditing"
|
||||
description: |-
|
||||
The `/sys/config/auditing` endpoint is used to configure auditing settings.
|
||||
---
|
||||
|
||||
# `/sys/config/auditing/request-headers`
|
||||
|
||||
The `/sys/config/auditing` endpoint is used to configure auditing settings.
|
||||
|
||||
## Read All Audited Request Headers
|
||||
|
||||
This endpoint lists the request headers that are configured to be audited.
|
||||
|
||||
- **`sudo` required** – This endpoint requires `sudo` capability in addition to
|
||||
any path-specific capabilities.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `GET` | `/sys/config/auditing/request-headers` | `200 application/json` |
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
https://vault.rocks/v1/sys/config/auditing/request-headers
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"headers": {
|
||||
"X-Forwarded-For": {
|
||||
"hmac": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Read Single Audit Request Header
|
||||
|
||||
This endpoint lists the information for the given request header.
|
||||
|
||||
- **`sudo` required** – This endpoint requires `sudo` capability in addition to
|
||||
any path-specific capabilities.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `POST` | `/sys/config/auditing/request-headers/:name` | `200 application/json` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `name` `(string: <required>)` – Specifies the name of the request header to
|
||||
query. This is specified as part of the URL.
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
https://vault.rocks/v1/sys/config/auditing/request-headers/my-header
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"X-Forwarded-For": {
|
||||
"hmac": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Create/Update Audit Request Header
|
||||
|
||||
This endpoint enables auditing of a header.
|
||||
|
||||
- **`sudo` required** – This endpoint requires `sudo` capability in addition to
|
||||
any path-specific capabilities.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `PUT` | `/sys/config/auditing/request-headers/:name` | `204 (empty body)` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `hmac` `(bool: false)` – Specifies if this header's value should be HMAC'ed in
|
||||
the audit logs.
|
||||
|
||||
### Sample Payload
|
||||
|
||||
```json
|
||||
{
|
||||
"hmac": true
|
||||
}
|
||||
```
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request PUT \
|
||||
--data payload.json \
|
||||
https://vault.rocks/v1/sys/config/auditing/request-headers/my-header
|
||||
```
|
||||
|
||||
## Delete Audit Request Header
|
||||
|
||||
This endpoint disables auditing of the given request header.
|
||||
|
||||
- **`sudo` required** – This endpoint requires `sudo` capability in addition to
|
||||
any path-specific capabilities.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `DELETE` | `/sys/config/auditing/request-headers/:name` | `204 (empty body)` |
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request DELETE \
|
||||
https://vault.rocks/v1/sys/config/auditing/request-headers/my-header
|
||||
```
|
||||
170
website/source/docs/http/system/generate-root.html.md
Normal file
170
website/source/docs/http/system/generate-root.html.md
Normal file
|
|
@ -0,0 +1,170 @@
|
|||
---
|
||||
layout: "http"
|
||||
page_title: "/sys/generate-root - HTTP API"
|
||||
sidebar_current: "docs-http-system-generate-root"
|
||||
description: |-
|
||||
The `/sys/generate-root/` endpoints are used to create a new root key for
|
||||
Vault.
|
||||
---
|
||||
|
||||
# `/sys/generate-root`
|
||||
|
||||
The `/sys/generate-root` endpoint is used to create a new root key for Vault.
|
||||
|
||||
## Read Root Generation Progress
|
||||
|
||||
This endpoint reads the configuration and process of the current root generation
|
||||
attempt.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `GET` | `/sys/generate-root/attempt` | `200 application/json` |
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
https://vault.rocks/v1/sys/generate-root/attempt
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"started": true,
|
||||
"nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63",
|
||||
"progress": 1,
|
||||
"required": 3,
|
||||
"encoded_root_token": "",
|
||||
"pgp_fingerprint": "",
|
||||
"complete": false
|
||||
}
|
||||
```
|
||||
|
||||
If a root generation is started, `progress` is how many unseal keys have been
|
||||
provided for this generation attempt, where `required` must be reached to
|
||||
complete. The `nonce` for the current attempt and whether the attempt is
|
||||
complete is also displayed. If a PGP key is being used to encrypt the final root
|
||||
token, its fingerprint will be returned. Note that if an OTP is being used to
|
||||
encode the final root token, it will never be returned.
|
||||
|
||||
## Start Root Token Generation
|
||||
|
||||
This endpoint initializes a new root generation attempt. Only a single root
|
||||
generation attempt can take place at a time. One (and only one) of `otp` or
|
||||
`pgp_key` are required.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `PUT` | `/sys/generate-root/attempt` | `200 application/json` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `otp` `(string: <required-unless-pgp>)` – Specifies a base64-encoded 16-byte
|
||||
value. The raw bytes of the token will be XOR'd with this value before being
|
||||
returned to the final unseal key provider.
|
||||
|
||||
- `pgp_key` `(string: <required-unless-otp>)` – Specifies a base64-encoded PGP
|
||||
public key. The raw bytes of the token will be encrypted with this value
|
||||
before being returned to the final unseal key provider.
|
||||
|
||||
### Sample Payload
|
||||
|
||||
```json
|
||||
{
|
||||
"otp": "CB23=="
|
||||
}
|
||||
```
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--request PUT \
|
||||
--data payload.json \
|
||||
https://vault.rocks/v1/sys/generate-root/attempt
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"started": true,
|
||||
"nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63",
|
||||
"progress": 1,
|
||||
"required": 3,
|
||||
"encoded_root_token": "",
|
||||
"pgp_fingerprint": "816938b8a29146fbe245dd29e7cbaf8e011db793",
|
||||
"complete": false
|
||||
}
|
||||
```
|
||||
|
||||
## Cancel Root Generation
|
||||
|
||||
This endpoint cancels any in-progress root generation attempt. This clears any
|
||||
progress made. This must be called to change the OTP or PGP key being used.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `DELETE` | `/sys/generate-root/attempt` | `204 (empty body)` |
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--request DELETE \
|
||||
https://vault.rocks/v1/sys/generate-root/attempt
|
||||
```
|
||||
|
||||
## Provide Key Share to Generate Root
|
||||
|
||||
This endpoint is used to enter a single master key share to progress the root
|
||||
generation attempt. If the threshold number of master key shares is reached,
|
||||
Vault will complete the root generation and issue the new token. Otherwise,
|
||||
this API must be called multiple times until that threshold is met. The attempt
|
||||
nonce must be provided with each call.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `PUT` | `/sys/generate-root/update` | `200 application/json` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `key` `(string: <required>)` – Specifies a single master key share.
|
||||
|
||||
- `nonce` `(string: <required>)` – Specifies the nonce of the attempt.
|
||||
|
||||
### Sample Payload
|
||||
|
||||
```json
|
||||
{
|
||||
"key": "acbd1234",
|
||||
"nonce": "ad235",
|
||||
}
|
||||
```
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--request PUT \
|
||||
--data payload.json \
|
||||
https://vault.rocks/v1/sys/generate-root/update
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
This returns a JSON-encoded object indicating the attempt nonce, and completion
|
||||
status, and the encoded root token, if the attempt is complete.
|
||||
|
||||
```json
|
||||
{
|
||||
"started": true,
|
||||
"nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63",
|
||||
"progress": 3,
|
||||
"required": 3,
|
||||
"pgp_fingerprint": "",
|
||||
"complete": true,
|
||||
"encoded_root_token": "FPzkNBvwNDeFh4SmGA8c+w=="
|
||||
}
|
||||
```
|
||||
71
website/source/docs/http/system/health.html.md
Normal file
71
website/source/docs/http/system/health.html.md
Normal file
|
|
@ -0,0 +1,71 @@
|
|||
---
|
||||
layout: "http"
|
||||
page_title: "/sys/health - HTTP API"
|
||||
sidebar_current: "docs-http-system-health"
|
||||
description: |-
|
||||
The `/sys/health` endpoint is used to check the health status of Vault.
|
||||
---
|
||||
|
||||
# `/sys/health`
|
||||
|
||||
The `/sys/health` endpoint is used to check the health status of Vault.
|
||||
|
||||
## Read Health Information
|
||||
|
||||
This endpoint returns the health status of Vault. This matches the semantics of
|
||||
a Consul HTTP health check and provides a simple way to monitor the health of a
|
||||
Vault instance.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `HEAD` | `/sys/health` | `000 (empty body)` |
|
||||
| `GET` | `/sys/health` | `000 application/json` |
|
||||
|
||||
The default status codes are:
|
||||
|
||||
- `200` if initialized, unsealed, and active
|
||||
- `429` if unsealed and standby
|
||||
- `501` if not initialized
|
||||
- `503` if sealed
|
||||
|
||||
### Parameters
|
||||
|
||||
- `standbyok` `(bool: false)` – Specifies if being a standby should still return
|
||||
the active status code instead of the standby status code. This is useful when
|
||||
Vault is behind a non-configurable load balance that just wants a 200-level
|
||||
response.
|
||||
|
||||
- `activecode` `(int: 200)` – Specifies the status code that should be returned
|
||||
for an active node.
|
||||
|
||||
- `standbycode` `(int: 429)` – Specifies the status code that should be returned
|
||||
for a standby node.
|
||||
|
||||
- `sealedcode` `(int: 503)` – Specifies the status code that should be returned
|
||||
for a sealed node.
|
||||
|
||||
- `uninitcode` `(int: 501)` – Specifies the status code that should be returned
|
||||
for a uninitialized node.
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
https://vault.rocks/v1/sys/health
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
This response is only returned for a `GET` request.
|
||||
|
||||
```json
|
||||
{
|
||||
"cluster_id": "c9abceea-4f46-4dab-a688-5ce55f89e228",
|
||||
"cluster_name": "vault-cluster-5515c810",
|
||||
"version": "0.6.2",
|
||||
"server_time_utc": 1469555798,
|
||||
"standby": false,
|
||||
"sealed": false,
|
||||
"initialized": true
|
||||
}
|
||||
```
|
||||
17
website/source/docs/http/system/index.html.md
Normal file
17
website/source/docs/http/system/index.html.md
Normal file
|
|
@ -0,0 +1,17 @@
|
|||
---
|
||||
layout: "http"
|
||||
page_title: "System Backend - HTTP API"
|
||||
sidebar_current: "docs-http-system"
|
||||
description: |-
|
||||
The system backend is a default backend in Vault that is mounted at the `/sys`
|
||||
endpoint. This endpoint cannot be unmounted or moved, and is used to configure
|
||||
Vault and interact with many of Vault's internal features.
|
||||
---
|
||||
|
||||
# System Backend
|
||||
|
||||
The system backend is a default backend in Vault that is mounted at the `/sys`
|
||||
endpoint. This endpoint cannot be unmounted or moved, and is used to configure
|
||||
Vault and interact with many of Vault's internal features.
|
||||
|
||||
For more information about a particular path, please click on it in the sidebar.
|
||||
112
website/source/docs/http/system/init.html.md
Normal file
112
website/source/docs/http/system/init.html.md
Normal file
|
|
@ -0,0 +1,112 @@
|
|||
---
|
||||
layout: "http"
|
||||
page_title: "/sys/init - HTTP API"
|
||||
sidebar_current: "docs-http-system-init"
|
||||
description: |-
|
||||
The `/sys/init` endpoint is used to initialize a new Vault.
|
||||
---
|
||||
|
||||
# `/sys/init`
|
||||
|
||||
The `/sys/init` endpoint is used to initialize a new Vault.
|
||||
|
||||
## Read Initialization Status
|
||||
|
||||
This endpoint returns the initialization status of Vault.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `GET` | `/sys/init` | `200 application/json` |
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
https://vault.rocks/v1/sys/init
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"initialized": true
|
||||
}
|
||||
```
|
||||
|
||||
## Start Initialization
|
||||
|
||||
This endpoint initializes a new Vault. The Vault must not have been previously
|
||||
initialized. The recovery options, as well as the stored shares option, are only
|
||||
available when using Vault HSM.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `PUT` | `/sys/init` | `200 application/json` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `pgp_keys` `(array<string>: nil)` – Specifies an array of PGP public keys used
|
||||
to encrypt the output unseal keys. Ordering is preserved. The keys must be
|
||||
base64-encoded from their original binary representation. The size of this
|
||||
array must be the same as `secret_shares`.
|
||||
|
||||
- `root_token_pgp_key` `(string: "")` – Specifies a PGP public key used to
|
||||
encrypt the initial root token. The key must be base64-encoded from its
|
||||
original binary representation.
|
||||
|
||||
- `secret_shares` `(int: <required>)` – Specifies the number of shares to
|
||||
split the master key into.
|
||||
|
||||
- `secret_threshold` `(int: <required>)` – Specifies the number of shares
|
||||
required to reconstruct the master key. This must be less than or equal
|
||||
`secret_shares`. If using Vault HSM with auto-unsealing, this value must be
|
||||
the same as `secret_shares`.
|
||||
|
||||
Additionally, the following options are only supported on Vault Pro/Enterprise:
|
||||
|
||||
- `stored_shares` `(int: <required>)` – Specifies the number of shares that
|
||||
should be encrypted by the HSM and stored for auto-unsealing. Currently must
|
||||
be the same as `secret_shares`.
|
||||
|
||||
- `recovery_shares` `(int: <required>)` – Specifies rhe number of shares to
|
||||
split the recovery key into.
|
||||
|
||||
- `recovery_threshold` `(int: <required>)` – Specifies rhe number of shares
|
||||
required to reconstruct the recovery key. This must be less than or equal to
|
||||
`recovery_shares`.
|
||||
|
||||
- `recovery_pgp_keys` `(array<string>: nil)` – Specifies an array of PGP public
|
||||
keys used to encrypt the output recovery keys. Ordering is preserved. The keys
|
||||
must be base64-encoded from their original binary representation. The size of
|
||||
this array must be the same as `recovery_shares`.
|
||||
|
||||
### Sample Payload
|
||||
|
||||
```json
|
||||
{
|
||||
"secret_shares": 10,
|
||||
"secret_threshold": 5
|
||||
}
|
||||
```
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--request PUT \
|
||||
--data payload.json \
|
||||
https://vault.rocks/v1/sys/init
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
A JSON-encoded object including the (possibly encrypted, if `pgp_keys` was
|
||||
provided) master keys, base 64 encoded master keys and initial root token:
|
||||
|
||||
```json
|
||||
{
|
||||
"keys": ["one", "two", "three"],
|
||||
"keys_base64": ["cR9No5cBC", "F3VLrkOo", "zIDSZNGv"],
|
||||
"root_token": "foo"
|
||||
}
|
||||
```
|
||||
37
website/source/docs/http/system/key-status.html.md
Normal file
37
website/source/docs/http/system/key-status.html.md
Normal file
|
|
@ -0,0 +1,37 @@
|
|||
---
|
||||
layout: "http"
|
||||
page_title: "/sys/key-status - HTTP API"
|
||||
sidebar_current: "docs-http-system-key-status"
|
||||
description: |-
|
||||
The `/sys/key-status` endpoint is used to query info about the current
|
||||
encryption key of Vault.
|
||||
---
|
||||
|
||||
# `/sys/key-status`
|
||||
|
||||
The `/sys/key-status` endpoint is used to query info about the current
|
||||
encryption key of Vault.
|
||||
|
||||
## Get Encryption Key Status
|
||||
|
||||
This endpoint returns information about the current encryption key used by
|
||||
Vault.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `GET` | `/sys/key-status` | `200 application/json` |
|
||||
|
||||
|
||||
### Sample Request
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"term": 3,
|
||||
"install_time": "2015-05-29T14:50:46.223692553-07:00"
|
||||
}
|
||||
```
|
||||
|
||||
The `term` parameter is the sequential key number, and `install_time` is the
|
||||
time that encryption key was installed.
|
||||
39
website/source/docs/http/system/leader.html.md
Normal file
39
website/source/docs/http/system/leader.html.md
Normal file
|
|
@ -0,0 +1,39 @@
|
|||
---
|
||||
layout: "http"
|
||||
page_title: "/sys/leader - HTTP API"
|
||||
sidebar_current: "docs-http-system-leader"
|
||||
description: |-
|
||||
The `/sys/leader` endpoint is used to check the high availability status and
|
||||
current leader of Vault.
|
||||
---
|
||||
|
||||
# `/sys/leader`
|
||||
|
||||
The `/sys/leader` endpoint is used to check the high availability status and
|
||||
current leader of Vault.
|
||||
|
||||
## Read Leader Status
|
||||
|
||||
This endpoint returns the high availability status and current leader instance
|
||||
of Vault.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `GET` | `/sys/leader` | `200 application/json` |
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
https://vault.rocks/v1/sys/leader
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"ha_enabled": true,
|
||||
"is_self": false,
|
||||
"leader_address": "https://127.0.0.1:8200/"
|
||||
}
|
||||
```
|
||||
188
website/source/docs/http/system/mounts.html.md
Normal file
188
website/source/docs/http/system/mounts.html.md
Normal file
|
|
@ -0,0 +1,188 @@
|
|||
---
|
||||
layout: "http"
|
||||
page_title: "/sys/mounts - HTTP API"
|
||||
sidebar_current: "docs-http-system-mounts"
|
||||
description: |-
|
||||
The `/sys/mounts` endpoint is used manage secret backends in Vault.
|
||||
---
|
||||
|
||||
# `/sys/mounts`
|
||||
|
||||
The `/sys/mounts` endpoint is used manage secret backends in Vault.
|
||||
|
||||
## List Mounted Secret Backends
|
||||
|
||||
This endpoints lists all the mounted secret backends.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `GET` | `/sys/mounts` | `200 application/json` |
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
https://vault.rocks/v1/sys/mounts
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"aws": {
|
||||
"type": "aws",
|
||||
"description": "AWS keys",
|
||||
"config": {
|
||||
"default_lease_ttl": 0,
|
||||
"max_lease_ttl": 0,
|
||||
"force_no_cache": false
|
||||
}
|
||||
},
|
||||
"sys": {
|
||||
"type": "system",
|
||||
"description": "system endpoint",
|
||||
"config": {
|
||||
"default_lease_ttl": 0,
|
||||
"max_lease_ttl": 0,
|
||||
"force_no_cache": false
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`default_lease_ttl` or `max_lease_ttl` values of 0 mean that the system defaults
|
||||
are used by this backend.
|
||||
|
||||
## Mount Secret Backend
|
||||
|
||||
This endpoint mounts a new secret backend at the given path.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `POST` | `/sys/mounts/:path` | `204 (empty body)` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `path` `(string: <required>)` – Specifies the path where the secret backend
|
||||
will be mounted. This is specified as part of the URL.
|
||||
|
||||
- `type` `(string: <required>)` – Specifies the type of the backend, such as
|
||||
"aws".
|
||||
|
||||
- `description` `(string: "")` – Specifies the human-friendly description of the
|
||||
mount.
|
||||
|
||||
- `config` `(map<string|string>: nil)` – Specifies configuration options for
|
||||
this mount. This is an object with three possible values:
|
||||
|
||||
- `default_lease_ttl`
|
||||
- `max_lease_ttl`
|
||||
- `force_no_cache`
|
||||
|
||||
These control the default and maximum lease time-to-live, and force
|
||||
disabling backend caching respectively. If set on a specific mount, this
|
||||
overrides the global defaults.
|
||||
|
||||
### Sample Payload
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "aws",
|
||||
"config": {
|
||||
"force_no_cache": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request POST \
|
||||
--data payload.json \
|
||||
https://vault.rocks/v1/sys/mounts/my-mount
|
||||
```
|
||||
|
||||
## Unmount Secret Backend
|
||||
|
||||
This endpoint un-mounts the mount point specified in the URL.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `DELETE` | `/sys/mounts/:path` | `204 (empty body) ` |
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request DELETE \
|
||||
https://vault.rocks/v1/sys/mounts/my-mount
|
||||
```
|
||||
|
||||
## Read Mount Configuration
|
||||
|
||||
This endpoint reads the given mount's configuration. Unlike the `mounts`
|
||||
endpoint, this will return the current time in seconds for each TTL, which may
|
||||
be the system default or a mount-specific value.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `GET` | `/sys/mounts/:path/tune` | `200 application/json` |
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
https://vault.rocks/v1/sys/mounts/my-mount/tune
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"default_lease_ttl": 3600,
|
||||
"max_lease_ttl": 7200,
|
||||
"force_no_cache": false
|
||||
}
|
||||
```
|
||||
|
||||
## Tune Mount Configuration
|
||||
|
||||
This endpoint tunes configuration parameters for a given mount point.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `POST` | `/sys/mounts/:path/tune` | `204 (empty body)` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `default_lease_ttl` `(int: 0)` – Specifies the default time-to-live. This
|
||||
overrides the global default. A value of `0` is equivalent to the system
|
||||
default TTL.
|
||||
|
||||
- `max_lease_ttl` `(int: 0)` – Specifies the maximum time-to-live. This
|
||||
overrides the global default. A value of `0` are equivalent and set to the
|
||||
system max TTL.
|
||||
|
||||
### Sample Payload
|
||||
|
||||
```json
|
||||
{
|
||||
"default_lease_ttl": 1800,
|
||||
"max_lease_ttl": 3600
|
||||
}
|
||||
```
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request POST \
|
||||
--data payload.json \
|
||||
https://vault.rocks/v1/sys/mounts/my-mount/tune
|
||||
```
|
||||
121
website/source/docs/http/system/policy.html.md
Normal file
121
website/source/docs/http/system/policy.html.md
Normal file
|
|
@ -0,0 +1,121 @@
|
|||
---
|
||||
layout: "http"
|
||||
page_title: "/sys/policy - HTTP API"
|
||||
sidebar_current: "docs-http-system-policy"
|
||||
description: |-
|
||||
The `/sys/policy` endpoint is used to manage ACL policies in Vault.
|
||||
---
|
||||
|
||||
# `/sys/policy`
|
||||
|
||||
The `/sys/policy` endpoint is used to manage ACL policies in Vault.
|
||||
|
||||
## List Policies
|
||||
|
||||
This endpoint lists all configured policies.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `GET` | `/sys/policy` | `200 application/json` |
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
https://vault.rocks/v1/sys/policy
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"policies": ["root", "deploy"]
|
||||
}
|
||||
```
|
||||
|
||||
## Read Policy
|
||||
|
||||
This endpoint retrieve the rules for the named policy.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `GET` | `/sys/policy/:name` | `200 application/json` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `name` `(string: <required>)` – Specifies the name of the policy to retrieve.
|
||||
This is specified as part of the request URL.
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
https://vault.rocks/v1/sys/policy/my-policy
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"rules": "path \"secret/foo\" {..."
|
||||
}
|
||||
```
|
||||
|
||||
## Create/Update Policy
|
||||
|
||||
This endpoint adds a new or updates an existing policy. Once a policy is
|
||||
updated, it takes effect immediately to all associated users.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `PUT` | `/sys/policy/:name` | `204 (empty body)` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `name` `(string: <required>)` – Specifies the name of the policy to create.
|
||||
This is specified as part of the request URL.
|
||||
|
||||
- `rules` `(string: <required>)` - Specifies the policy document.
|
||||
|
||||
### Sample Payload
|
||||
|
||||
```json
|
||||
{
|
||||
"rules": "path \"secret/foo\" {..."
|
||||
}
|
||||
```
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request PUT \
|
||||
--data payload.json \
|
||||
https://vault.rocks/v1/sys/policy/my-policy
|
||||
```
|
||||
|
||||
## Delete Policy
|
||||
|
||||
This endpoint deletes the policy with the given name. This will immediately
|
||||
affect all users associated with this policy.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `DELETE` | `/sys/policy/:name` | `204 (empty body)` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `name` `(string: <required>)` – Specifies the name of the policy to delete.
|
||||
This is specified as part of the request URL.
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request DELETE \
|
||||
https://vault.rocks/v1/sys/policy/my-policy
|
||||
```
|
||||
100
website/source/docs/http/system/raw.html.md
Normal file
100
website/source/docs/http/system/raw.html.md
Normal file
|
|
@ -0,0 +1,100 @@
|
|||
---
|
||||
layout: "http"
|
||||
page_title: "/sys/raw - HTTP API"
|
||||
sidebar_current: "docs-http-system-raw"
|
||||
description: |-
|
||||
The `/sys/raw` endpoint is access the raw underlying store in Vault.
|
||||
---
|
||||
|
||||
# `/sys/raw`
|
||||
|
||||
The `/sys/raw` endpoint is access the raw underlying store in Vault.
|
||||
|
||||
## Read Raw
|
||||
|
||||
This endpoint reads the value of the key at the given path. This is the raw path
|
||||
in the storage backend and not the logical path that is exposed via the mount
|
||||
system.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `GET` | `/sys/raw/:path` | `200 application/json` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `path` `(string: <required>)` – Specifies the raw path in the storage backend.
|
||||
This is specified as part of the URL.
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
---header "X-Vault-Token: ..." \
|
||||
https://vault.rocks/v1/sys/raw/secret/foo
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"value": "{'foo':'bar'}"
|
||||
}
|
||||
```
|
||||
|
||||
## Create/Update Raw
|
||||
|
||||
This endpoint updates the value of the key at the given path. This is the raw
|
||||
path in the storage backend and not the logical path that is exposed via the
|
||||
mount system.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `PUT` | `/sys/raw/:path` | `204 (empty body)` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `path` `(string: <required>)` – Specifies the raw path in the storage backend.
|
||||
This is specified as part of the URL.
|
||||
|
||||
- `value` `(string: <required>)` – Specifies the value of the key.
|
||||
|
||||
### Sample Payload
|
||||
|
||||
```json
|
||||
{
|
||||
"value": "{\"foo\": \"bar\"}"
|
||||
}
|
||||
```
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request PUT \
|
||||
--data @payload.json \
|
||||
https://vault.rocks/v1/sys/raw/secret/foo
|
||||
```
|
||||
|
||||
## Delete Raw
|
||||
|
||||
This endpoint deletes the key with given path. This is the raw path in the
|
||||
storage backend and not the logical path that is exposed via the mount system.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `DELETE` | `/sys/raw/:path` | `204 (empty body)` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `path` `(string: <required>)` – Specifies the raw path in the storage backend.
|
||||
This is specified as part of the URL.
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request DELETE \
|
||||
https://vault.rocks/v1/sys/raw/secret/foo
|
||||
```
|
||||
217
website/source/docs/http/system/rekey.html.md
Normal file
217
website/source/docs/http/system/rekey.html.md
Normal file
|
|
@ -0,0 +1,217 @@
|
|||
---
|
||||
layout: "http"
|
||||
page_title: "/sys/rekey - HTTP API"
|
||||
sidebar_current: "docs-http-system-rekey"
|
||||
description: |-
|
||||
The `/sys/rekey` endpoints are used to rekey the unseal keys for Vault.
|
||||
---
|
||||
|
||||
# `/sys/rekey`
|
||||
|
||||
The `/sys/rekey` endpoints are used to rekey the unseal keys for Vault.
|
||||
|
||||
## Read Rekey Progress
|
||||
|
||||
This endpoint reads the configuration and progress of the current rekey attempt.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `GET` | `/sys/rekey/init` | `200 application/json` |
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
https://vault.rocks/v1/sys/rekey/init
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"started": true,
|
||||
"nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63",
|
||||
"t": 3,
|
||||
"n": 5,
|
||||
"progress": 1,
|
||||
"required": 3,
|
||||
"pgp_fingerprints": ["abcd1234"],
|
||||
"backup": true
|
||||
}
|
||||
```
|
||||
|
||||
If a rekey is started, then `n` is the new shares to generate and `t` is the
|
||||
threshold required for the new shares. `progress` is how many unseal keys have
|
||||
been provided for this rekey, where `required` must be reached to complete. The
|
||||
`nonce` for the current rekey operation is also displayed. If PGP keys are being
|
||||
used to encrypt the final shares, the key fingerprints and whether the final
|
||||
keys will be backed up to physical storage will also be displayed.
|
||||
|
||||
|
||||
## Start Rekey
|
||||
|
||||
This endpoint initializes a new rekey attempt. Only a single rekey attempt can
|
||||
take place at a time, and changing the parameters of a rekey requires canceling
|
||||
and starting a new rekey, which will also provide a new nonce.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `PUT` | `/sys/rekey/init` | `204 (empty body)` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `secret_shares` `(int: <required>)` – Specifies the number of shares to split
|
||||
the master key into.
|
||||
|
||||
- `secret_threshold` `(int: <required>)` – Specifies the number of shares
|
||||
required to reconstruct the master key. This must be less than or equal to
|
||||
`secret_shares`.
|
||||
|
||||
- `pgp_keys` `(array<string>: nil)` – Specifies an array of PGP public keys used
|
||||
to encrypt the output unseal keys. Ordering is preserved. The keys must be
|
||||
base64-encoded from their original binary representation. The size of this
|
||||
array must be the same as `secret_shares`.
|
||||
|
||||
- `backup` `(bool: false)` – Specifies if using PGP-encrypted keys, whether
|
||||
Vault should also back them up to `core/unseal-keys-backup` in the physical
|
||||
storage backend. These can then be retrieved and removed via the
|
||||
`sys/rekey/backup` endpoint.
|
||||
|
||||
### Sample Payload
|
||||
|
||||
```json
|
||||
{
|
||||
"secret_shares": 10,
|
||||
"secret_threshold": 5
|
||||
}
|
||||
```
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request PUT \
|
||||
--data @payload.json \
|
||||
https://vault.rocks/v1/sys/rekey/init
|
||||
```
|
||||
|
||||
## Cancel Rekey
|
||||
|
||||
This endpoint cancels any in-progress rekey. This clears the rekey settings as
|
||||
well as any progress made. This must be called to change the parameters of the
|
||||
rekey.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `DELETE` | `/sys/rekey/init` | `204 (empty body)` |
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request DELETE \
|
||||
https://vault.rocks/v1/sys/rekey/init
|
||||
```
|
||||
|
||||
## Read Backup Key
|
||||
|
||||
This endpoint returns the backup copy of PGP-encrypted unseal keys. The returned
|
||||
value is the nonce of the rekey operation and a map of PGP key fingerprint to
|
||||
hex-encoded PGP-encrypted key.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `GET` | `/sys/rekey/backup` | `200 application/json` |
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
https://vault.rocks/v1/sys/rekey/backup
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63",
|
||||
"keys": {
|
||||
"abcd1234": "..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Delete Backup Key
|
||||
|
||||
This endpoint deletes the backup copy of PGP-encrypted unseal keys.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `DELETE` | `/sys/rekey/backup` | `204 (empty body)` |
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token" \
|
||||
--request DELETE \
|
||||
https://vault.rocks/v1/sys/rekey/backup
|
||||
```
|
||||
|
||||
## Submit Key
|
||||
|
||||
This endpoint is used to enter a single master key share to progress the rekey
|
||||
of the Vault. If the threshold number of master key shares is reached, Vault
|
||||
will complete the rekey. Otherwise, this API must be called multiple times until
|
||||
that threshold is met. The rekey nonce operation must be provided with each
|
||||
call.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `PUT` | `/sys/rekey/update` | `200 application/json` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `key` `(string: <required>)` – Specifies a single master share key.
|
||||
|
||||
- `nonce` `(string: <required>)` – Specifies the nonce of the rekey operation.
|
||||
|
||||
### Sample Payload
|
||||
|
||||
```json
|
||||
{
|
||||
"key": "abcd1234...",
|
||||
"nonce": "AB32..."
|
||||
}
|
||||
```
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token" \
|
||||
--request PUT \
|
||||
--data @payload.json \
|
||||
https://vault.rocks/v1/sys/rekey/update
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"complete": true,
|
||||
"keys": ["one", "two", "three"],
|
||||
"nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63",
|
||||
"pgp_fingerprints": ["abcd1234"],
|
||||
"keys_base64": ["base64keyvalue"],
|
||||
"backup": true
|
||||
}
|
||||
```
|
||||
|
||||
If the keys are PGP-encrypted, an array of key fingerprints will also be
|
||||
provided (with the order in which the keys were used for encryption) along with
|
||||
whether or not the keys were backed up to physical storage.
|
||||
44
website/source/docs/http/system/remount.html.md
Normal file
44
website/source/docs/http/system/remount.html.md
Normal file
|
|
@ -0,0 +1,44 @@
|
|||
---
|
||||
layout: "http"
|
||||
page_title: "/sys/remount - HTTP API"
|
||||
sidebar_current: "docs-http-system-remount"
|
||||
description: |-
|
||||
The '/sys/remount' endpoint is used remount a mounted backend to a new endpoint.
|
||||
---
|
||||
|
||||
# `/sys/remount`
|
||||
|
||||
The `/sys/remount` endpoint is used remount a mounted backend to a new endpoint.
|
||||
|
||||
## Remount Backend
|
||||
|
||||
This endpoint remounts an already-mounted backend to a new mount point.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `POST` | `/sys/remount` | `204 (empty body)` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `from` `(string: <required>)` – Specifies the previous mount point.
|
||||
|
||||
- `to` `(string: <required>)` – Specifies the new destination mount point.
|
||||
|
||||
### Sample Payload
|
||||
|
||||
```json
|
||||
{
|
||||
"from": "secret",
|
||||
"to": "new-secret"
|
||||
}
|
||||
```
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request POST \
|
||||
--data @payload.json \
|
||||
https://vault.rocks/v1/sys/remount
|
||||
```
|
||||
68
website/source/docs/http/system/renew.html.md
Normal file
68
website/source/docs/http/system/renew.html.md
Normal file
|
|
@ -0,0 +1,68 @@
|
|||
---
|
||||
layout: "http"
|
||||
page_title: "/sys/renew - HTTP API"
|
||||
sidebar_current: "docs-http-system-renew"
|
||||
description: |-
|
||||
The `/sys/renew` endpoint is used to renew secrets.
|
||||
---
|
||||
|
||||
# `/sys/renew`
|
||||
|
||||
The `/sys/renew` endpoint is used to renew secrets.
|
||||
|
||||
## Renew Secret
|
||||
|
||||
This endpoint renews a secret, requesting to extend the lease.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `PUT` | `/sys/renew/(:lease_id)` | `200 application/json` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `lease_id` `(string: <required>)` – Specifies the ID of the lease to extend.
|
||||
This can be specified as part of the URL or as part of the request body.
|
||||
|
||||
- `increment` `(int: 0)` – Specifies the requested amount of time (in seconds)
|
||||
to extend the lease.
|
||||
|
||||
### Sample Payload
|
||||
|
||||
```json
|
||||
{
|
||||
"lease_id": "postgresql/creds/readonly/abcd-1234...",
|
||||
"increment": 1800
|
||||
}
|
||||
```
|
||||
|
||||
### Sample Request
|
||||
|
||||
With the `lease_id` as part of the URL:
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request PUT \
|
||||
--data @payload.json \
|
||||
https://vault.rocks/v1/sys/renew/postgresql/creds/readonly/abcd-1234
|
||||
```
|
||||
|
||||
With the `lease_id` in the request body:
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request PUT \
|
||||
--data @payload.json \
|
||||
https://vault.rocks/v1/sys/renew
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"lease_id": "aws/creds/deploy/e31b1145-ff27-e62c-cba2-934e9f0d1dbc",
|
||||
"renewable": true,
|
||||
"lease_duration": 2764790
|
||||
}
|
||||
```
|
||||
43
website/source/docs/http/system/revoke-force.html.md
Normal file
43
website/source/docs/http/system/revoke-force.html.md
Normal file
|
|
@ -0,0 +1,43 @@
|
|||
---
|
||||
layout: "http"
|
||||
page_title: "/sys/revoke-force - HTTP API"
|
||||
sidebar_current: "docs-http-system-revoke-force"
|
||||
description: |-
|
||||
The `/sys/revoke-force` endpoint is used to revoke secrets or tokens based on
|
||||
prefix while ignoring backend errors.
|
||||
---
|
||||
|
||||
# `/sys/revoke-force`
|
||||
|
||||
The `/sys/revoke-force` endpoint is used to revoke secrets or tokens based on
|
||||
prefix while ignoring backend errors.
|
||||
|
||||
## Revoke Force
|
||||
|
||||
This endpoint revokes all secrets or tokens generated under a given prefix
|
||||
immediately. Unlike `/sys/revoke-prefix`, this path ignores backend errors
|
||||
encountered during revocation. This is _potentially very dangerous_ and should
|
||||
only be used in specific emergency situations where errors in the backend or the
|
||||
connected backend service prevent normal revocation.
|
||||
|
||||
By ignoring these errors, Vault abdicates responsibility for ensuring that the
|
||||
issued credentials or secrets are properly revoked and/or cleaned up. Access to
|
||||
this endpoint should be tightly controlled.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `PUT` | `/sys/revoke-force/:prefix` | `204 (empty body)` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `prefix` `(string: <required>)` – Specifies the prefix to revoke. This is
|
||||
specified as part of the URL.
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request PUT \
|
||||
https://vault.rocks/v1/sys/revoke-force/aws/creds
|
||||
```
|
||||
38
website/source/docs/http/system/revoke-prefix.html.md
Normal file
38
website/source/docs/http/system/revoke-prefix.html.md
Normal file
|
|
@ -0,0 +1,38 @@
|
|||
---
|
||||
layout: "http"
|
||||
page_title: "/sys/revoke-prefix - HTTP API"
|
||||
sidebar_current: "docs-http-system-revoke-prefix"
|
||||
description: |-
|
||||
The `/sys/revoke-prefix` endpoint is used to revoke secrets or tokens based on
|
||||
prefix.
|
||||
---
|
||||
|
||||
# `/sys/revoke-prefix`
|
||||
|
||||
The `/sys/revoke-prefix` endpoint is used to revoke secrets or tokens based on
|
||||
prefix.
|
||||
|
||||
## Revoke Prefix
|
||||
|
||||
This endpoint revokes all secrets (via a lease ID prefix) or tokens (via the
|
||||
tokens' path property) generated under a given prefix immediately. This requires
|
||||
`sudo` capability and access to it should be tightly controlled as it can be
|
||||
used to revoke very large numbers of secrets/tokens at once.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `PUT` | `/sys/revoke-prefix/:prefix` | `204 (empty body)` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `prefix` `(string: <required>)` – Specifies the prefix to revoke. This is
|
||||
specified as part of the URL.
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request PUT \
|
||||
https://vault.rocks/v1/sys/revoke-prefix/aws/creds
|
||||
```
|
||||
32
website/source/docs/http/system/revoke.html.md
Normal file
32
website/source/docs/http/system/revoke.html.md
Normal file
|
|
@ -0,0 +1,32 @@
|
|||
---
|
||||
layout: "http"
|
||||
page_title: "/sys/revoke - HTTP API"
|
||||
sidebar_current: "docs-http-system-revoke/"
|
||||
description: |-
|
||||
The `/sys/revoke` endpoint is used to revoke secrets.
|
||||
---
|
||||
|
||||
# `/sys/revoke`
|
||||
|
||||
The `/sys/revoke` endpoint is used to revoke secrets.
|
||||
|
||||
## Revoke Secret
|
||||
|
||||
This endpoint revokes a secret immediately.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `PUT` | `/sys/revoke/:lease_id` | `204 (empty body)` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `lease_id` `(string: <required>)` – Specifies the ID of the lease to renew.
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request PUT \
|
||||
https://vault.rocks/v1/sys/revoke/aws/creds/readonly-acbd1234
|
||||
```
|
||||
31
website/source/docs/http/system/rotate.html.md
Normal file
31
website/source/docs/http/system/rotate.html.md
Normal file
|
|
@ -0,0 +1,31 @@
|
|||
---
|
||||
layout: "http"
|
||||
page_title: "/sys/rotate - HTTP API"
|
||||
sidebar_current: "docs-http-system-rotate"
|
||||
description: |-
|
||||
The `/sys/rotate` endpoint is used to rotate the encryption key.
|
||||
---
|
||||
|
||||
# `/sys/rotate`
|
||||
|
||||
The `/sys/rotate` endpoint is used to rotate the encryption key.
|
||||
|
||||
## Rotate Encryption Key
|
||||
|
||||
This endpoint triggers a rotation of the backend encryption key. This is the key
|
||||
that is used to encrypt data written to the storage backend, and is not provided
|
||||
to operators. This operation is done online. Future values are encrypted with
|
||||
the new key, while old values are decrypted with previous encryption keys.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `PUT` | `/sys/rotate` | `204 (empty body)` |
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request PUT \
|
||||
https://vault.rocks/v1/sys/rotate
|
||||
```
|
||||
55
website/source/docs/http/system/seal-status.html.md
Normal file
55
website/source/docs/http/system/seal-status.html.md
Normal file
|
|
@ -0,0 +1,55 @@
|
|||
---
|
||||
layout: "http"
|
||||
page_title: "/sys/seal-status - HTTP API"
|
||||
sidebar_current: "docs-http-system-seal-status"
|
||||
description: |-
|
||||
The `/sys/seal-status` endpoint is used to check the seal status of a Vault.
|
||||
---
|
||||
|
||||
# `/sys/seal-status`
|
||||
|
||||
The `/sys/seal-status` endpoint is used to check the seal status of a Vault.
|
||||
|
||||
## Seal Status
|
||||
|
||||
This endpoint returns the seal status of the Vault. This is an unauthenticated
|
||||
endpoint.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `GET` | `/sys/seal-status` | `200 application/json` |
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
https://vault.rocks/v1/sys/seal-status
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
The "t" parameter is the threshold, and "n" is the number of shares.
|
||||
|
||||
```json
|
||||
{
|
||||
"sealed": true,
|
||||
"t": 3,
|
||||
"n": 5,
|
||||
"progress": 2,
|
||||
"version": "0.6.2"
|
||||
}
|
||||
```
|
||||
|
||||
Sample response when Vault is unsealed.
|
||||
|
||||
```json
|
||||
{
|
||||
"sealed": false,
|
||||
"t": 3,
|
||||
"n": 5,
|
||||
"progress": 0,
|
||||
"version": "0.6.2",
|
||||
"cluster_name": "vault-cluster-d6ec3c7f",
|
||||
"cluster_id": "3e8b3fec-3749-e056-ba41-b62a63b997e8"
|
||||
}
|
||||
```
|
||||
30
website/source/docs/http/system/seal.html.md
Normal file
30
website/source/docs/http/system/seal.html.md
Normal file
|
|
@ -0,0 +1,30 @@
|
|||
---
|
||||
layout: "http"
|
||||
page_title: "/sys/seal - HTTP API"
|
||||
sidebar_current: "docs-http-system-seal/"
|
||||
description: |-
|
||||
The `/sys/seal` endpoint seals the Vault.
|
||||
---
|
||||
|
||||
# `/sys/seal`
|
||||
|
||||
The `/sys/seal` endpoint seals the Vault.
|
||||
|
||||
## Seal
|
||||
|
||||
This endpoint seals the Vault. In HA mode, only an active node can be sealed.
|
||||
Standby nodes should be restarted to get the same effect. Requires a token with
|
||||
`root` policy or `sudo` capability on the path.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `PUT` | `/sys/seal` | `204 (empty body)` |
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request PUT \
|
||||
https://vault.rocks/v1/sys/seal
|
||||
```
|
||||
33
website/source/docs/http/system/step-down.html.md
Normal file
33
website/source/docs/http/system/step-down.html.md
Normal file
|
|
@ -0,0 +1,33 @@
|
|||
---
|
||||
layout: "http"
|
||||
page_title: "/sys/step-down - HTTP API"
|
||||
sidebar_current: "docs-http-system-step-down"
|
||||
description: |-
|
||||
The `/sys/step-down` endpoint causes the node to give up active status.
|
||||
---
|
||||
|
||||
# `/sys/step-down`
|
||||
|
||||
The `/sys/step-down` endpoint causes the node to give up active status.
|
||||
|
||||
## Step Down Leader
|
||||
|
||||
This endpoint forces the node to give up active status. If the node does not
|
||||
have active status, this endpoint does nothing. Note that the node will sleep
|
||||
for ten seconds before attempting to grab the active lock again, but if no
|
||||
standby nodes grab the active lock in the interim, the same node may become the
|
||||
active node again. Requires a token with `root` policy or `sudo` capability on
|
||||
the path.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `PUT` | `/sys/step-down` | `204 (empty body)` |
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request PUT \
|
||||
https://vault.rocks/v1/sys/step-down
|
||||
```
|
||||
78
website/source/docs/http/system/unseal.html.md
Normal file
78
website/source/docs/http/system/unseal.html.md
Normal file
|
|
@ -0,0 +1,78 @@
|
|||
---
|
||||
layout: "http"
|
||||
page_title: "/sys/seal-unseal - HTTP API"
|
||||
sidebar_current: "docs-http-system-unseal"
|
||||
description: |-
|
||||
The `/sys/seal-unseal` endpoint is used to unseal the Vault.
|
||||
---
|
||||
|
||||
# `/sys/unseal`
|
||||
|
||||
The `/sys/seal-unseal` endpoint is used to unseal the Vault.
|
||||
|
||||
## Submit Unseal Key
|
||||
|
||||
This endpoint is used to enter a single master key share to progress the
|
||||
unsealing of the Vault. If the threshold number of master key shares is reached,
|
||||
Vault will attempt to unseal the Vault. Otherwise, this API must be called
|
||||
multiple times until that threshold is met.
|
||||
|
||||
Either the `key` or `reset` parameter must be provided; if both are provided,
|
||||
`reset` takes precedence.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `PUT` | `/sys/unseal` | `200 application/json` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `key` `(string: "")` – Specifies a single master key share. This is required
|
||||
unless `reset` is true.
|
||||
|
||||
- `reset` `(bool: false)` – Specifies if previously-provided unseal keys are
|
||||
discarded and the unseal process is reset.
|
||||
|
||||
### Sample Payload
|
||||
|
||||
```json
|
||||
{
|
||||
"key": "abcd1234..."
|
||||
}
|
||||
```
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--request PUT \
|
||||
--data @payload.json \
|
||||
https://vault.rocks/v1/sys/unseal
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
The "t" parameter is the threshold, and "n" is the number of shares.
|
||||
|
||||
```json
|
||||
{
|
||||
"sealed": true,
|
||||
"t": 3,
|
||||
"n": 5,
|
||||
"progress": 2,
|
||||
"version": "0.6.2"
|
||||
}
|
||||
```
|
||||
|
||||
Sample response when Vault is unsealed.
|
||||
|
||||
```json
|
||||
{
|
||||
"sealed": false,
|
||||
"t": 3,
|
||||
"n": 5,
|
||||
"progress": 0,
|
||||
"version": "0.6.2",
|
||||
"cluster_name": "vault-cluster-d6ec3c7f",
|
||||
"cluster_id": "3e8b3fec-3749-e056-ba41-b62a63b997e8"
|
||||
}
|
||||
```
|
||||
57
website/source/docs/http/system/wrapping-lookup.html.md
Normal file
57
website/source/docs/http/system/wrapping-lookup.html.md
Normal file
|
|
@ -0,0 +1,57 @@
|
|||
---
|
||||
layout: "http"
|
||||
page_title: "/sys/wrapping/lookup - HTTP API"
|
||||
sidebar_current: "docs-http-system-wrapping-lookup"
|
||||
description: |-
|
||||
The `/sys/wrapping/lookup` endpoint returns wrapping token properties.
|
||||
---
|
||||
|
||||
# `/sys/wrapping/lookup`
|
||||
|
||||
The `/sys/wrapping/lookup` endpoint returns wrapping token properties.
|
||||
|
||||
## Wrapping Lookup
|
||||
|
||||
This endpoint looks up wrapping properties for the given token.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `POST` | `/sys/wrapping/lookup` | `200 application/json` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `token` `(string: <required>)` – Specifies the wrapping token ID.
|
||||
|
||||
### Sample Payload
|
||||
|
||||
```json
|
||||
{
|
||||
"token": "abcd1234"
|
||||
}
|
||||
```
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request POST \
|
||||
--data @payload.json \
|
||||
https://vault.rocks/v1/sys/wrapping/lookup
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"request_id": "481320f5-fdf8-885d-8050-65fa767fd19b",
|
||||
"lease_id": "",
|
||||
"lease_duration": 0,
|
||||
"renewable": false,
|
||||
"data": {
|
||||
"creation_time": "2016-09-28T14:16:13.07103516-04:00",
|
||||
"creation_ttl": 300
|
||||
},
|
||||
"warnings": null
|
||||
}
|
||||
```
|
||||
64
website/source/docs/http/system/wrapping-rewrap.html.md
Normal file
64
website/source/docs/http/system/wrapping-rewrap.html.md
Normal file
|
|
@ -0,0 +1,64 @@
|
|||
---
|
||||
layout: "http"
|
||||
page_title: "/sys/wrapping/rewrap - HTTP API"
|
||||
sidebar_current: "docs-http-system-wrapping-rewrap"
|
||||
description: |-
|
||||
The `/sys/wrapping/rewrap` endpoint can be used to rotate a wrapping token and refresh its TTL.
|
||||
---
|
||||
|
||||
# `/sys/wrapping/rewrap`
|
||||
|
||||
The `/sys/wrapping/rewrap` endpoint can be used to rotate a wrapping token and
|
||||
refresh its TTL.
|
||||
|
||||
## Wrapping Rewrap
|
||||
|
||||
This endpoint rewraps a response-wrapped token. The new token will use the same
|
||||
creation TTL as the original token and contain the same response. The old token
|
||||
will be invalidated. This can be used for long-term storage of a secret in a
|
||||
response-wrapped token when rotation is a requirement.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `POST` | `/sys/wrapping/rewrap` | `200 application/json` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `token` `(string: <required>)` – Specifies the wrapping token ID.
|
||||
|
||||
### Sample Payload
|
||||
|
||||
```json
|
||||
{
|
||||
"token": "abcd1234...",
|
||||
}
|
||||
```
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request POST \
|
||||
--data @payload.json \
|
||||
https://vault.rocks/v1/sys/wrapping/lookup
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"request_id": "",
|
||||
"lease_id": "",
|
||||
"lease_duration": 0,
|
||||
"renewable": false,
|
||||
"data": null,
|
||||
"warnings": null,
|
||||
"wrap_info": {
|
||||
"token": "3b6f1193-0707-ac17-284d-e41032e74d1f",
|
||||
"ttl": 300,
|
||||
"creation_time": "2016-09-28T14:22:26.486186607-04:00",
|
||||
"wrapped_accessor": ""
|
||||
}
|
||||
}
|
||||
```
|
||||
69
website/source/docs/http/system/wrapping-unwrap.html.md
Normal file
69
website/source/docs/http/system/wrapping-unwrap.html.md
Normal file
|
|
@ -0,0 +1,69 @@
|
|||
---
|
||||
layout: "http"
|
||||
page_title: "/sys/wrapping/unwrap - HTTP API"
|
||||
sidebar_current: "docs-http-system-wrapping-unwrap"
|
||||
description: |-
|
||||
The `/sys/wrapping/unwrap` endpoint unwraps a wrapped response.
|
||||
---
|
||||
|
||||
# `/sys/wrapping/unwrap`
|
||||
|
||||
The `/sys/wrapping/unwrap` endpoint unwraps a wrapped response.
|
||||
|
||||
## Wrapping Unwrap
|
||||
|
||||
This endpoint returns the original response inside the given wrapping token.
|
||||
Unlike simply reading `cubbyhole/response` (which is deprecated), this endpoint
|
||||
provides additional validation checks on the token, returns the original value
|
||||
on the wire rather than a JSON string representation of it, and ensures that the
|
||||
response is properly audit-logged.
|
||||
|
||||
This endpoint can be used by using a wrapping token as the client token in the
|
||||
API call, in which case the `token` parameter is not required; or, a different
|
||||
token with permissions to access this endpoint can make the call and pass in the
|
||||
wrapping token in the `token` parameter. Do _not_ use the wrapping token in both
|
||||
locations; this will cause the wrapping token to be revoked but the value to be
|
||||
unable to be looked up, as it will basically be a double-use of the token!
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `POST` | `/sys/wrapping/unwrap` | `200 application/json` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `token` `(string: "")` – Specifies the wrapping token ID. This is required if
|
||||
the client token is not the wrapping token. Do not use the wrapping token in
|
||||
both locations.
|
||||
|
||||
### Sample Payload
|
||||
|
||||
```json
|
||||
{
|
||||
"token": "abcd1234..."
|
||||
}
|
||||
```
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request POST \
|
||||
--data @payload.json \
|
||||
https://vault.rocks/v1/sys/wrapping/unwrap
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"request_id": "8e33c808-f86c-cff8-f30a-fbb3ac22c4a8",
|
||||
"lease_id": "",
|
||||
"lease_duration": 2592000,
|
||||
"renewable": false,
|
||||
"data": {
|
||||
"zip": "zap"
|
||||
},
|
||||
"warnings": null
|
||||
}
|
||||
```
|
||||
66
website/source/docs/http/system/wrapping-wrap.html.md
Normal file
66
website/source/docs/http/system/wrapping-wrap.html.md
Normal file
|
|
@ -0,0 +1,66 @@
|
|||
---
|
||||
layout: "http"
|
||||
page_title: "/sys/wrapping/wrap - HTTP API"
|
||||
sidebar_current: "docs-http-system-wrapping-wrap"
|
||||
description: |-
|
||||
The `/sys/wrapping/wrap` endpoint wraps the given values in a
|
||||
response-wrapped token.
|
||||
---
|
||||
|
||||
# `/sys/wrapping/wrap`
|
||||
|
||||
The `/sys/wrapping/wrap` endpoint wraps the given values in a response-wrapped
|
||||
token.
|
||||
|
||||
## Wrapping Wrap
|
||||
|
||||
This endpoint wraps the given user-supplied data inside a response-wrapped
|
||||
token.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `POST` | `/sys/wrapping/wrap` | `200 application/json` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `:any` `(map<string|string>: nil)` – Parameters should be supplied as
|
||||
keys/values in a JSON object. The exact set of given parameters will be
|
||||
contained in the wrapped response.
|
||||
|
||||
### Sample Payload
|
||||
|
||||
```json
|
||||
{
|
||||
"foo": "bar",
|
||||
"zip": "zap"
|
||||
}
|
||||
```
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request POST \
|
||||
--data @payload.json \
|
||||
https://vault.rocks/v1/sys/wrapping/wrap
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"request_id": "",
|
||||
"lease_id": "",
|
||||
"lease_duration": 0,
|
||||
"renewable": false,
|
||||
"data": null,
|
||||
"warnings": null,
|
||||
"wrap_info": {
|
||||
"token": "fb79b9d3-d94e-9eb6-4919-c559311133d6",
|
||||
"ttl": 300,
|
||||
"creation_time": "2016-09-28T14:41:00.56961496-04:00",
|
||||
"wrapped_accessor": ""
|
||||
}
|
||||
}
|
||||
```
|
||||
Loading…
Reference in a new issue