diff --git a/website/source/assets/stylesheets/_api.scss b/website/source/assets/stylesheets/_api.scss index 5bc1dc2a19..4a3d654658 100644 --- a/website/source/assets/stylesheets/_api.scss +++ b/website/source/assets/stylesheets/_api.scss @@ -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; diff --git a/website/source/docs/http/sys-audit-hash.html.md b/website/source/docs/http/sys-audit-hash.html.md deleted file mode 100644 index d4dcc8c374..0000000000 --- a/website/source/docs/http/sys-audit-hash.html.md +++ /dev/null @@ -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 - -
-
Description
-
- 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. -
- -
Method
-
POST
- -
URL
-
`/sys/audit-hash/`
- -
Parameters
-
- -
- -
Returns
-
- - ```javascript - { - "hash": "hmac-sha256:08ba357e274f528065766c770a639abf6809b39ccfd37c2a3157c7f51954da0a" - } - ``` - -
-
diff --git a/website/source/docs/http/sys-audit.html.md b/website/source/docs/http/sys-audit.html.md deleted file mode 100644 index 3d494155bc..0000000000 --- a/website/source/docs/http/sys-audit.html.md +++ /dev/null @@ -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 - -
-
Description
-
- List the mounted audit backends. _This endpoint requires `sudo` - capability._ -
- -
Method
-
GET
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "file": { - "type": "file", - "description": "Store logs in a file", - "options": { - "path": "/var/log/file" - } - } - } - ``` - -
-
- -## PUT - -
-
Description
-
- Enable an audit backend. _This endpoint requires `sudo` capability._ -
- -
Method
-
PUT
- -
URL
-
`/sys/audit/`
- -
Parameters
-
- -
- -
Returns
-
`204` response code. -
-
- -## DELETE - -
-
Description
-
- Disable the given audit backend. _This endpoint requires `sudo` - capability._ -
- -
Method
-
DELETE
- -
URL
-
`/sys/audit/`
- -
Parameters
-
None -
- -
Returns
-
`204` response code. -
-
diff --git a/website/source/docs/http/sys-auth.html.md b/website/source/docs/http/sys-auth.html.md deleted file mode 100644 index e60ea88718..0000000000 --- a/website/source/docs/http/sys-auth.html.md +++ /dev/null @@ -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 - -
-
Description
-
- Lists all the enabled auth backends. -
- -
Method
-
GET
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "github": { - "type": "github", - "description": "GitHub auth" - } - } - ``` - -
-
- -## POST - -
-
Description
-
- 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._ -
- -
Method
-
POST
- -
URL
-
`/sys/auth/`
- -
Parameters
-
- -
- -
Returns
-
`204` response code. -
-
- -## DELETE - -
-
Description
-
- Disable the auth backend at the given auth path. _This endpoint requires - `sudo` capability on the final path._ -
- -
Method
-
DELETE
- -
URL
-
`/sys/auth/`
- -
Parameters
-
None -
- -
Returns
-
`204` response code. -
-
- -# /sys/auth/[auth-path]/tune - -## GET - -
-
Description
-
- 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`._ -
- -
Method
-
GET
- -
URL
-
`/sys/auth/[auth-path]/tune`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "default_lease_ttl": 3600, - "max_lease_ttl": 7200 - } - ``` - -
-
- -## POST - -
-
Description
-
- 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`._ -
- -
Method
-
POST
- -
URL
-
`/sys/auth/[auth-path]/tune`
- -
Parameters
-
- -
- -
Returns
-
`204` response code. -
-
diff --git a/website/source/docs/http/sys-capabilities-accessor.html.md b/website/source/docs/http/sys-capabilities-accessor.html.md deleted file mode 100644 index c707ddf618..0000000000 --- a/website/source/docs/http/sys-capabilities-accessor.html.md +++ /dev/null @@ -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 - -
-
Description
-
- Returns the capabilities of the token associated with an accessor, on the given path. -
- -
Method
-
POST
- -
Parameters
-
- -
- -
Returns
-
- - ```javascript - { - "capabilities": ["read", "list"] - } - ``` - -
-
diff --git a/website/source/docs/http/sys-capabilities-self.html.md b/website/source/docs/http/sys-capabilities-self.html.md deleted file mode 100644 index f581da5f34..0000000000 --- a/website/source/docs/http/sys-capabilities-self.html.md +++ /dev/null @@ -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 - -
-
Description
-
- Returns the capabilities of client token on the given path. - Client token is the Vault token with which this API call is made. -
- -
Method
-
POST
- -
Parameters
-
- -
- -
Returns
-
- - ```javascript - { - "capabilities": ["read", "list"] - } - ``` - -
-
diff --git a/website/source/docs/http/sys-capabilities.html.md b/website/source/docs/http/sys-capabilities.html.md deleted file mode 100644 index 0375bb515e..0000000000 --- a/website/source/docs/http/sys-capabilities.html.md +++ /dev/null @@ -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 - -
-
Description
-
- Returns the capabilities of the token on the given path. -
- -
Method
-
POST
- -
Parameters
-
- -
- -
Returns
-
- - ```javascript - { - "capabilities": ["read", "list"] - } - ``` - -
-
diff --git a/website/source/docs/http/sys-config-auditing.html.md b/website/source/docs/http/sys-config-auditing.html.md deleted file mode 100644 index 36bfda8362..0000000000 --- a/website/source/docs/http/sys-config-auditing.html.md +++ /dev/null @@ -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 - -
-
Description
-
- List the request headers that are configured to be audited. _This endpoint requires `sudo` - capability._ -
- -
Method
-
GET
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "headers": { - "X-Forwarded-For": { - "hmac":true - } - } - } - ``` - -
-
- -# /sys/config/auditing/request-headers/ - -## GET - -
-
Description
-
- List the information for the given request header. _This endpoint requires `sudo` - capability._ -
- -
Method
-
GET
- -
URL
-
`/sys/config/auditing/request-headers/`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "X-Forwarded-For": { - "hmac":true - } - } - ``` - -
-
- -## PUT - -
-
Description
-
- Enable auditing of a header. _This endpoint requires `sudo` capability._ -
- -
Method
-
PUT
- -
URL
-
`/sys/config/auditing/request-headers/`
- -
Parameters
-
- -
- -
Returns
-
`204` response code. -
-
- -## DELETE - -
-
Description
-
- Disable auditing of the given request header. _This endpoint requires `sudo` - capability._ -
- -
Method
-
DELETE
- -
URL
-
`/sys/config/auditing/request-headers/`
- -
Parameters
-
None -
- -
Returns
-
`204` response code. -
-
diff --git a/website/source/docs/http/sys-generate-root.html.md b/website/source/docs/http/sys-generate-root.html.md deleted file mode 100644 index 01a77b28c6..0000000000 --- a/website/source/docs/http/sys-generate-root.html.md +++ /dev/null @@ -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 - -
-
Description
-
- Reads the configuration and progress of the current root generation - attempt. -
- -
Method
-
GET
- -
URL
-
`/sys/generate-root/attempt`
- -
Parameters
-
- None -
- -
Returns
-
- 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 - } - ``` - -
-
- -## PUT - -
-
Description
-
- 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
-
PUT
- -
URL
-
`/sys/generate-root/attempt`
- -
Parameters
-
- -
- -
Returns
-
- The current progress. - - ```javascript - { - "started": true, - "nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63", - "progress": 1, - "required": 3, - "encoded_root_token": "", - "pgp_fingerprint": "816938b8a29146fbe245dd29e7cbaf8e011db793", - "complete": false - } - ``` - -
-
- -## DELETE - -
-
Description
-
- 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
-
DELETE
- -
URL
-
`/sys/generate-root/attempt`
- -
Parameters
-
None -
- -
Returns
-
`204` response code. -
-
- -# /sys/generate-root/update - -## PUT - -
-
Description
-
- 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
-
PUT
- -
URL
-
`/sys/generate-root/update`
- -
Parameters
-
- -
- -
Returns
-
- 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==" - } - ``` - -
-
diff --git a/website/source/docs/http/sys-health.html.md b/website/source/docs/http/sys-health.html.md deleted file mode 100644 index 7b1248751b..0000000000 --- a/website/source/docs/http/sys-health.html.md +++ /dev/null @@ -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 - -
-
Description
-
- 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
-
GET/HEAD
- -
Parameters
-
- -
- -
Returns (only with GET)
-
- - ```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. -
-
diff --git a/website/source/docs/http/sys-init.html.md b/website/source/docs/http/sys-init.html.md deleted file mode 100644 index f403e02ad9..0000000000 --- a/website/source/docs/http/sys-init.html.md +++ /dev/null @@ -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 - -
-
Description
-
- Return the initialization status of a Vault. -
- -
Method
-
GET
- -
Parameters
-
None
- -
Returns
-
- - ```javascript - { - "initialized": true - } - ``` - -
-
- -## PUT - -
-
Description
-
- 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
-
PUT
- -
Parameters
-
- -
- -
Returns
-
- A JSON-encoded object including the (possibly encrypted, if - pgp_keys 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" - } - ``` - -
- -
See Also
-
- For more information on the PGP/Keybase.io process please see the - [Vault GPG and Keybase integration documentation](/docs/concepts/pgp-gpg-keybase.html). -
-
diff --git a/website/source/docs/http/sys-key-status.html.md b/website/source/docs/http/sys-key-status.html.md deleted file mode 100644 index 74d3ffde24..0000000000 --- a/website/source/docs/http/sys-key-status.html.md +++ /dev/null @@ -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 - -
-
Description
-
- Returns information about the current encryption key used by Vault. -
- -
Method
-
GET
- -
Parameters
-
- None -
- -
Returns
-
- 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" - } - ``` - -
-
diff --git a/website/source/docs/http/sys-leader.html.md b/website/source/docs/http/sys-leader.html.md deleted file mode 100644 index 273ac3102c..0000000000 --- a/website/source/docs/http/sys-leader.html.md +++ /dev/null @@ -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 - -
-
Description
-
- Returns the high availability status and current leader instance of Vault. -
- -
Method
-
GET
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "ha_enabled": true, - "is_self": false, - "leader_address": "https://127.0.0.1:8200/" - } - ``` - -
-
diff --git a/website/source/docs/http/sys-mounts.html.md b/website/source/docs/http/sys-mounts.html.md deleted file mode 100644 index 489c672bab..0000000000 --- a/website/source/docs/http/sys-mounts.html.md +++ /dev/null @@ -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 - -
-
Description
-
- 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. -
- -
Method
-
GET
- -
URL
-
`/sys/mounts`
- -
Parameters
-
- None -
- -
Returns
-
- - ```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 - } - } - } - ``` - -
-
- -## POST - -
-
Description
-
- Mount a new secret backend to the mount point in the URL. -
- -
Method
-
POST
- -
URL
-
`/sys/mounts/`
- -
Parameters
-
- -
- -
Returns
-
`204` response code. -
-
- -## DELETE - -
-
Description
-
- Unmount the mount point specified in the URL. -
- -
Method
-
DELETE
- -
URL
-
`/sys/mounts/`
- -
Parameters
-
None -
- -
Returns
-
`204` response code. -
-
- -# /sys/mounts/[mount point]/tune - -## GET - -
-
Description
-
- 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. -
- -
Method
-
GET
- -
URL
-
`/sys/mounts//tune`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "default_lease_ttl": 3600, - "max_lease_ttl": 7200, - "force_no_cache": false - } - ``` - -
-
- -## POST - -
-
Description
-
- Tune configuration parameters for a given mount point. -
- -
Method
-
POST
- -
URL
-
`/sys/mounts//tune`
- -
Parameters
-
- -
- -
Returns
-
`204` response code. -
-
diff --git a/website/source/docs/http/sys-policy.html.md b/website/source/docs/http/sys-policy.html.md deleted file mode 100644 index 22eb920bc5..0000000000 --- a/website/source/docs/http/sys-policy.html.md +++ /dev/null @@ -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 - -
-
Description
-
- Lists all the available policies. -
- -
Method
-
GET
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "policies": ["root", "deploy"] - } - ``` - -
-
- -# /sys/policy/ - -## GET - -
-
Description
-
- Retrieve the rules for the named policy. -
- -
Method
-
GET
- -
URL
-
`/sys/policy/`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "rules": "path..." - } - ``` - -
-
- - -## PUT - -
-
Description
-
- Add or update a policy. Once a policy is updated, it takes effect - immediately to all associated users. -
- -
Method
-
PUT
- -
URL
-
`/sys/policy/`
- -
Parameters
-
- -
- -
Returns
-
`204` response code. -
-
- -## DELETE - -
-
Description
-
- Delete the policy with the given name. This will immediately - affect all associated users. -
- -
Method
-
DELETE
- -
URL
-
`/sys/policy/`
- -
Parameters
-
None -
- -
Returns
-
`204` response code. -
-
diff --git a/website/source/docs/http/sys-raw.html.md b/website/source/docs/http/sys-raw.html.md deleted file mode 100644 index 2ce1a206ff..0000000000 --- a/website/source/docs/http/sys-raw.html.md +++ /dev/null @@ -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 - -
-
Description
-
- 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
-
GET
- -
URL
-
`/sys/raw/`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "value": "{'foo':'bar'}" - } - ``` - -
-
- -## PUT - -
-
Description
-
- 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. -
- -
Method
-
PUT
- -
URL
-
`/sys/raw/`
- -
Parameters
-
- -
- -
Returns
-
`204` response code. -
-
- -## DELETE - -
-
Description
-
- 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. -
- -
Method
-
DELETE
- -
URL
-
`/sys/raw/`
- -
Parameters
-
None -
- -
Returns
-
`204` response code. -
-
diff --git a/website/source/docs/http/sys-rekey.html.md b/website/source/docs/http/sys-rekey.html.md deleted file mode 100644 index 70260ac7a4..0000000000 --- a/website/source/docs/http/sys-rekey.html.md +++ /dev/null @@ -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 - -
-
Description
-
- Reads the configuration and progress of the current rekey attempt. -
- -
Method
-
GET
- -
URL
-
`/sys/rekey/init`
- -
Parameters
-
- None -
- -
Returns
-
- 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 - } - ``` - -
-
- -## PUT - -
-
Description
-
- 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
-
PUT
- -
URL
-
`/sys/rekey/init`
- -
Parameters
-
- -
- -
Returns
-
`204` response code. -
-
- -## DELETE - -
-
Description
-
- 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
-
DELETE
- -
URL
-
`/sys/rekey/init`
- -
Parameters
-
None -
- -
Returns
-
`204` response code. -
-
- -# /sys/rekey/backup - -## GET - -
-
Description
-
- 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. -
- -
Method
-
GET
- -
URL
-
`/sys/rekey/backup`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63", - "keys": { - "abcd1234": "..." - } - } - ``` - -
-
- -## DELETE - -
-
Description
-
- Delete the backup copy of PGP-encrypted unseal keys. -
- -
Method
-
DELETE
- -
URL
-
`/sys/rekey/backup`
- -
Parameters
-
None -
- -
Returns
-
`204` response code. -
-
- -# /sys/rekey/update - -## PUT - -
-
Description
-
- 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
-
PUT
- -
URL
-
`/sys/rekey/update`
- -
Parameters
-
- -
- -
Returns
-
- 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 - } - ``` - -
-
diff --git a/website/source/docs/http/sys-remount.html.md b/website/source/docs/http/sys-remount.html.md deleted file mode 100644 index 231e770920..0000000000 --- a/website/source/docs/http/sys-remount.html.md +++ /dev/null @@ -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 - -
-
Description
-
- Remount an already-mounted backend to a new mount point. -
- -
Method
-
POST
- -
Parameters
-
- -
- -
Returns
-
`204` response code. -
-
diff --git a/website/source/docs/http/sys-renew.html.md b/website/source/docs/http/sys-renew.html.md deleted file mode 100644 index fdfbc62bda..0000000000 --- a/website/source/docs/http/sys-renew.html.md +++ /dev/null @@ -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 - -
-
Description
-
- Renew a secret, requesting to extend the lease. -
- -
Method
-
PUT
- -
URL
-
`/sys/renew(/)`
- -
Parameters
-
- -
- -
Returns
-
A secret structure. -
-
diff --git a/website/source/docs/http/sys-revoke-force.html.md b/website/source/docs/http/sys-revoke-force.html.md deleted file mode 100644 index 9f30b1511a..0000000000 --- a/website/source/docs/http/sys-revoke-force.html.md +++ /dev/null @@ -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 - -
-
Description
-
- 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 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
-
PUT
- -
URL
-
`/sys/revoke-force/`
- -
Parameters
-
None
- -
Returns
-
A `204` response code. -
-
diff --git a/website/source/docs/http/sys-revoke-prefix.html.md b/website/source/docs/http/sys-revoke-prefix.html.md deleted file mode 100644 index 606758aabb..0000000000 --- a/website/source/docs/http/sys-revoke-prefix.html.md +++ /dev/null @@ -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 - -
-
Description
-
- 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. -
- -
Method
-
PUT
- -
URL
-
`/sys/revoke-prefix/`
- -
Parameters
-
None
- -
Returns
-
A `204` response code. -
-
diff --git a/website/source/docs/http/sys-revoke.html.md b/website/source/docs/http/sys-revoke.html.md deleted file mode 100644 index 04672c75d4..0000000000 --- a/website/source/docs/http/sys-revoke.html.md +++ /dev/null @@ -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 - -
-
Description
-
- Revoke a secret immediately. -
- -
Method
-
PUT
- -
URL
-
`/sys/revoke/`
- -
Parameters
-
None
- -
Returns
-
A `204` response code. -
-
diff --git a/website/source/docs/http/sys-rotate.html.md b/website/source/docs/http/sys-rotate.html.md deleted file mode 100644 index 7b5b070443..0000000000 --- a/website/source/docs/http/sys-rotate.html.md +++ /dev/null @@ -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 - -
-
Description
-
- 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. -
- -
Method
-
PUT
- -
URL
-
`/sys/rotate`
- -
Parameters
-
- None -
- -
Returns
-
`204` response code. -
-
- diff --git a/website/source/docs/http/sys-seal-status.html.md b/website/source/docs/http/sys-seal-status.html.md deleted file mode 100644 index f6fdc4758e..0000000000 --- a/website/source/docs/http/sys-seal-status.html.md +++ /dev/null @@ -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 - -
-
Description
-
- Returns the seal status of the Vault.

This is an unauthenticated endpoint. -
- -
Method
-
GET
- -
Parameters
-
- None -
- -
Returns
-
- 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" - } - ``` - -
-
diff --git a/website/source/docs/http/sys-seal.html.md b/website/source/docs/http/sys-seal.html.md deleted file mode 100644 index d82b9af386..0000000000 --- a/website/source/docs/http/sys-seal.html.md +++ /dev/null @@ -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 - -
-
Description
-
- 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
-
PUT
- -
Parameters
-
- None -
- -
Returns
-
A `204` response code. -
-
diff --git a/website/source/docs/http/sys-step-down.html.md b/website/source/docs/http/sys-step-down.html.md deleted file mode 100644 index 6e2f26617e..0000000000 --- a/website/source/docs/http/sys-step-down.html.md +++ /dev/null @@ -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 - -
-
Description
-
- 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
-
PUT
- -
Parameters
-
- None -
- -
Returns
-
A `204` response code. -
-
diff --git a/website/source/docs/http/sys-unseal.html.md b/website/source/docs/http/sys-unseal.html.md deleted file mode 100644 index 94f21a644c..0000000000 --- a/website/source/docs/http/sys-unseal.html.md +++ /dev/null @@ -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 - -
-
Description
-
- 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
-
PUT
- -
Parameters
-
- -
-
Returns
-
The same result as `/sys/seal-status`. -
-
diff --git a/website/source/docs/http/sys-wrapping-lookup.html.md b/website/source/docs/http/sys-wrapping-lookup.html.md deleted file mode 100644 index c2d1d66b9e..0000000000 --- a/website/source/docs/http/sys-wrapping-lookup.html.md +++ /dev/null @@ -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 - -
-
Description
-
- Looks up wrapping properties for the given token. -
- -
Method
-
POST
- -
URL
-
`/sys/wrapping/lookup`
- -
Parameters
-
- -
- -
Returns
-
- - ```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 - } - ``` - -
-
diff --git a/website/source/docs/http/sys-wrapping-rewrap.html.md b/website/source/docs/http/sys-wrapping-rewrap.html.md deleted file mode 100644 index 5fd3fc79b9..0000000000 --- a/website/source/docs/http/sys-wrapping-rewrap.html.md +++ /dev/null @@ -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 - -
-
Description
-
- 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
-
POST
- -
URL
-
`/sys/wrapping/rewrap`
- -
Parameters
-
- -
- -
Returns
-
- - ```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": "" - } - } - ``` - -
-
diff --git a/website/source/docs/http/sys-wrapping-unwrap.html.md b/website/source/docs/http/sys-wrapping-unwrap.html.md deleted file mode 100644 index 3532117e93..0000000000 --- a/website/source/docs/http/sys-wrapping-unwrap.html.md +++ /dev/null @@ -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 - -
-
Description
-
- 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
-
POST
- -
URL
-
`/sys/wrapping/unwrap`
- -
Parameters
-
- -
- -
Returns
-
- - ```javascript - { - "request_id": "8e33c808-f86c-cff8-f30a-fbb3ac22c4a8", - "lease_id": "", - "lease_duration": 2592000, - "renewable": false, - "data": { - "zip": "zap" - }, - "warnings": null - } - ``` - -
-
diff --git a/website/source/docs/http/sys-wrapping-wrap.html.md b/website/source/docs/http/sys-wrapping-wrap.html.md deleted file mode 100644 index ce69c57a3a..0000000000 --- a/website/source/docs/http/sys-wrapping-wrap.html.md +++ /dev/null @@ -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 - -
-
Description
-
- Wraps the given user-supplied data inside a response-wrapped token. -
- -
Method
-
POST
- -
URL
-
`/sys/wrapping/wrap`
- -
Parameters
-
- -
- -
Returns
-
- - ```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": "" - } - } - ``` - -
-
diff --git a/website/source/docs/http/system/audit-hash.html.md b/website/source/docs/http/system/audit-hash.html.md new file mode 100644 index 0000000000..add41dd74c --- /dev/null +++ b/website/source/docs/http/system/audit-hash.html.md @@ -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: )` – Specifies the path of the audit backend to + generate hashes for. This is part of the request URL. + +- `input` `(string: )` – 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..." +} +``` diff --git a/website/source/docs/http/system/audit.html.md b/website/source/docs/http/system/audit.html.md new file mode 100644 index 0000000000..f1720e5259 --- /dev/null +++ b/website/source/docs/http/system/audit.html.md @@ -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: )` – 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: nil)` – Specifies configuration options to + pass to the audit backend itself. This is dependent on the audit backend type. + +- `type` `(string: )` – 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: )` – 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 +``` diff --git a/website/source/docs/http/system/auth.html.md b/website/source/docs/http/system/auth.html.md new file mode 100644 index 0000000000..52ab68f6b9 --- /dev/null +++ b/website/source/docs/http/system/auth.html.md @@ -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: )` – 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: )` – 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: )` – 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: )` – 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 +``` diff --git a/website/source/docs/http/system/capabilities-accessor.html.md b/website/source/docs/http/system/capabilities-accessor.html.md new file mode 100644 index 0000000000..02f9299084 --- /dev/null +++ b/website/source/docs/http/system/capabilities-accessor.html.md @@ -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: )` – Specifies the accessor of the token to + check. + +- `path` `(string: )` – 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"] +} +``` diff --git a/website/source/docs/http/system/capabilities-self.html.md b/website/source/docs/http/system/capabilities-self.html.md new file mode 100644 index 0000000000..259928fc3e --- /dev/null +++ b/website/source/docs/http/system/capabilities-self.html.md @@ -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: )` – 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"] +} +``` diff --git a/website/source/docs/http/system/capabilities.html.md b/website/source/docs/http/system/capabilities.html.md new file mode 100644 index 0000000000..3faf9ebb86 --- /dev/null +++ b/website/source/docs/http/system/capabilities.html.md @@ -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: )` – Specifies the path against which to check the + token's capabilities. + +- `token` `(string: )` – 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"] +} +``` diff --git a/website/source/docs/http/system/config-auditing.html.md b/website/source/docs/http/system/config-auditing.html.md new file mode 100644 index 0000000000..22c4bf6919 --- /dev/null +++ b/website/source/docs/http/system/config-auditing.html.md @@ -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: )` – 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 +``` diff --git a/website/source/docs/http/system/generate-root.html.md b/website/source/docs/http/system/generate-root.html.md new file mode 100644 index 0000000000..2deacc5047 --- /dev/null +++ b/website/source/docs/http/system/generate-root.html.md @@ -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: )` – 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: )` – 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: )` – Specifies a single master key share. + +- `nonce` `(string: )` – 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==" +} +``` diff --git a/website/source/docs/http/system/health.html.md b/website/source/docs/http/system/health.html.md new file mode 100644 index 0000000000..2b9322b5ef --- /dev/null +++ b/website/source/docs/http/system/health.html.md @@ -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 +} +``` diff --git a/website/source/docs/http/system/index.html.md b/website/source/docs/http/system/index.html.md new file mode 100644 index 0000000000..f78d1e9274 --- /dev/null +++ b/website/source/docs/http/system/index.html.md @@ -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. diff --git a/website/source/docs/http/system/init.html.md b/website/source/docs/http/system/init.html.md new file mode 100644 index 0000000000..940211d818 --- /dev/null +++ b/website/source/docs/http/system/init.html.md @@ -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: 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: )` – Specifies the number of shares to + split the master key into. + +- `secret_threshold` `(int: )` – 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: )` – 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: )` – Specifies rhe number of shares to + split the recovery key into. + +- `recovery_threshold` `(int: )` – 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: 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" +} +``` diff --git a/website/source/docs/http/system/key-status.html.md b/website/source/docs/http/system/key-status.html.md new file mode 100644 index 0000000000..e7451494f9 --- /dev/null +++ b/website/source/docs/http/system/key-status.html.md @@ -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. diff --git a/website/source/docs/http/system/leader.html.md b/website/source/docs/http/system/leader.html.md new file mode 100644 index 0000000000..81200be13f --- /dev/null +++ b/website/source/docs/http/system/leader.html.md @@ -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/" +} +``` diff --git a/website/source/docs/http/system/mounts.html.md b/website/source/docs/http/system/mounts.html.md new file mode 100644 index 0000000000..27826f2805 --- /dev/null +++ b/website/source/docs/http/system/mounts.html.md @@ -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: )` – Specifies the path where the secret backend + will be mounted. This is specified as part of the URL. + +- `type` `(string: )` – Specifies the type of the backend, such as + "aws". + +- `description` `(string: "")` – Specifies the human-friendly description of the + mount. + +- `config` `(map: 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 +``` diff --git a/website/source/docs/http/system/policy.html.md b/website/source/docs/http/system/policy.html.md new file mode 100644 index 0000000000..8a21373540 --- /dev/null +++ b/website/source/docs/http/system/policy.html.md @@ -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: )` – 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: )` – Specifies the name of the policy to create. + This is specified as part of the request URL. + +- `rules` `(string: )` - 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: )` – 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 +``` diff --git a/website/source/docs/http/system/raw.html.md b/website/source/docs/http/system/raw.html.md new file mode 100644 index 0000000000..57ee5a225c --- /dev/null +++ b/website/source/docs/http/system/raw.html.md @@ -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: )` – 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: )` – Specifies the raw path in the storage backend. + This is specified as part of the URL. + +- `value` `(string: )` – 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: )` – 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 +``` diff --git a/website/source/docs/http/system/rekey.html.md b/website/source/docs/http/system/rekey.html.md new file mode 100644 index 0000000000..b3a61604f2 --- /dev/null +++ b/website/source/docs/http/system/rekey.html.md @@ -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: )` – Specifies the number of shares to split + the master key into. + +- `secret_threshold` `(int: )` – Specifies the number of shares + required to reconstruct the master key. This must be less than or equal to + `secret_shares`. + +- `pgp_keys` `(array: 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: )` – Specifies a single master share key. + +- `nonce` `(string: )` – 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. diff --git a/website/source/docs/http/system/remount.html.md b/website/source/docs/http/system/remount.html.md new file mode 100644 index 0000000000..8092984b3d --- /dev/null +++ b/website/source/docs/http/system/remount.html.md @@ -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: )` – Specifies the previous mount point. + +- `to` `(string: )` – 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 +``` diff --git a/website/source/docs/http/system/renew.html.md b/website/source/docs/http/system/renew.html.md new file mode 100644 index 0000000000..cbf05efc8b --- /dev/null +++ b/website/source/docs/http/system/renew.html.md @@ -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: )` – 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 +} +``` diff --git a/website/source/docs/http/system/revoke-force.html.md b/website/source/docs/http/system/revoke-force.html.md new file mode 100644 index 0000000000..ceac319bf4 --- /dev/null +++ b/website/source/docs/http/system/revoke-force.html.md @@ -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: )` – 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 +``` diff --git a/website/source/docs/http/system/revoke-prefix.html.md b/website/source/docs/http/system/revoke-prefix.html.md new file mode 100644 index 0000000000..ea3aa9b16a --- /dev/null +++ b/website/source/docs/http/system/revoke-prefix.html.md @@ -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: )` – 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 +``` diff --git a/website/source/docs/http/system/revoke.html.md b/website/source/docs/http/system/revoke.html.md new file mode 100644 index 0000000000..f670e889c6 --- /dev/null +++ b/website/source/docs/http/system/revoke.html.md @@ -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: )` – 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 +``` diff --git a/website/source/docs/http/system/rotate.html.md b/website/source/docs/http/system/rotate.html.md new file mode 100644 index 0000000000..69f6d86f05 --- /dev/null +++ b/website/source/docs/http/system/rotate.html.md @@ -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 +``` diff --git a/website/source/docs/http/system/seal-status.html.md b/website/source/docs/http/system/seal-status.html.md new file mode 100644 index 0000000000..2393629392 --- /dev/null +++ b/website/source/docs/http/system/seal-status.html.md @@ -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" +} +``` diff --git a/website/source/docs/http/system/seal.html.md b/website/source/docs/http/system/seal.html.md new file mode 100644 index 0000000000..59f369f170 --- /dev/null +++ b/website/source/docs/http/system/seal.html.md @@ -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 +``` diff --git a/website/source/docs/http/system/step-down.html.md b/website/source/docs/http/system/step-down.html.md new file mode 100644 index 0000000000..db39f43bf8 --- /dev/null +++ b/website/source/docs/http/system/step-down.html.md @@ -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 +``` diff --git a/website/source/docs/http/system/unseal.html.md b/website/source/docs/http/system/unseal.html.md new file mode 100644 index 0000000000..e0465f81fe --- /dev/null +++ b/website/source/docs/http/system/unseal.html.md @@ -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" +} +``` diff --git a/website/source/docs/http/system/wrapping-lookup.html.md b/website/source/docs/http/system/wrapping-lookup.html.md new file mode 100644 index 0000000000..bea4942b17 --- /dev/null +++ b/website/source/docs/http/system/wrapping-lookup.html.md @@ -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: )` – 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 +} +``` diff --git a/website/source/docs/http/system/wrapping-rewrap.html.md b/website/source/docs/http/system/wrapping-rewrap.html.md new file mode 100644 index 0000000000..edc1469225 --- /dev/null +++ b/website/source/docs/http/system/wrapping-rewrap.html.md @@ -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: )` – 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": "" + } +} +``` diff --git a/website/source/docs/http/system/wrapping-unwrap.html.md b/website/source/docs/http/system/wrapping-unwrap.html.md new file mode 100644 index 0000000000..1a2b466594 --- /dev/null +++ b/website/source/docs/http/system/wrapping-unwrap.html.md @@ -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 +} +``` diff --git a/website/source/docs/http/system/wrapping-wrap.html.md b/website/source/docs/http/system/wrapping-wrap.html.md new file mode 100644 index 0000000000..7a43a3df0d --- /dev/null +++ b/website/source/docs/http/system/wrapping-wrap.html.md @@ -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: 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": "" + } +} +```