HashiCorp Learn
Infrastructure
  • TerraformTerraformLearn terraformDocs
  • PackerPackerLearn packerDocs
  • VagrantVagrantLearn vagrantDocs
Security
  • VaultVaultLearn vaultDocs
  • BoundaryBoundaryLearn boundaryDocs
Networking
  • ConsulConsulLearn consulDocs
Applications
  • NomadNomadLearn nomadDocs
  • WaypointWaypointLearn waypointDocs
  • HashiCorp Cloud Platform (HCP) LogoHashiCorp Cloud Platform (HCP)HashiCorp Cloud Platform (HCP)Docs
Type '/' to Search
Loading account...
  • Bookmarks
  • Manage Account
  • Overview
  • Required policy
  • Access API Explorer
  • API endpoint examples
  • Next steps
  • Help and reference
DocsForum
Back to vault
UI Quick StartView Collection
    Getting Started with Vault UIInstall VaultWeb UICreate Vault PoliciesManage Authentication MethodsManage Secrets EnginesAPI Explorer in Vault UINext Steps

API Explorer in Vault UI

  • 8 min
  • Products Usedvault

The Vault UI includes a handy API explorer feature that you can use to both interactively learn about the Vault HTTP API and try live requests against your Vault cluster or dev mode server.

»Required policy

Your token ACL policy will limit the capabilities you have on the API endpoints.

For the purpose of this tutorial, a minimal policy including the paths used in all of UI tutorials can be found in this example. This way, you can try the underlying API endpoint paths that correspond with the auth method and secrets engine configured in the other tutorials.

Example tutorial policy named learn-ui-api:

# Read the configuration secret example
path "secret/config" {
    capabilities = ["read"]
}

# Read the host information example
path "sys/host-info" {
    capabilities = ["read"]
}

# List secrets engines
path "sys/mounts" {
    capabilities = ["read"]
}

# Enable Transit secrets engine
path "sys/mounts/transit" {
    capabilities = ["create", "update"]
}

# Manage Transit secrets engine keys
path "transit/keys" {
    capabilities = ["list"]
}
path "transit/keys/*" {
    capabilities = ["create", "list", "read", "update"]
}
path "transit/keys/+/config" {
    capabilities = ["create", "update"]
}

# Encrypt with any Transit secrets engine key
path "transit/encrypt/*" {
    capabilities = ["create", "update"]
}

# Decrypt with any Transit secrets engine key
path "transit/decrypt/*" {
    capabilities = ["create", "update"]
}

You need to Sign out and use the root_token value you copy from the downloaded key file to sign back in to create a new policy since webapp policy does not grant permission to create policies.

Use the steps from Create Vault Policies tutorial with a highly privileged token to create this policy. Name it learn-ui-api.

You can then attach the learn-ui-api policy to the userpass auth method that you configured in the Manage Authentication Methods tutorial.

Edit user

Although you can continue working with the root token, the best practice is to sign out of the UI and sign in with the userpass auth method. By doing so, you are practicing the principle of least privilege by having only the capabilities required to complete this tutorial.

Once you have signed into Vault as webapp user, proceed with the rest of the tutorial.

»Access API Explorer

To access the API explorer, open the browser CLI by choosing the terminal icon as shown in the navigation screen shot.

The CLI will open to reveal a > prompt. Type help at any time to get help with using it.

Access the API explorer by typing api at the prompt and pressing return.

A warning is emitted for the first access to the API explorer, you should read and carefully understand it before experimenting with requests, particularly when using a highly privileged token.

WARNING: The "Try it out" functionality in this API explorer will make requests to this Vault server on your behalf. IF YOUR TOKEN HAS THE PROPER CAPABILITIES, THIS WILL CREATE AND DELETE ITEMS ON THE VAULT SERVER. Your token will also be shown on the screen in the example curl command output.

»API endpoint examples

You can select the browser CLI icon again to close the CLI, as it is only used to launch the API explorer.

You are now ready to explore some API endpoints.

»/sys/host-info

Vault version 1.3 introduced /sys/host-info a handy API endpoint for getting underlying host system information.

The example policy included in this tutorial provides the capability to access this API endpoint provided that you have authenticated to Vault with a token that has the policy attached.

To quickly locate the endpoint in the list, use the search and enter /sys/host-info. This will narrow the results to a single entry for GET operations.

Select the GET entry and then select Try it out; a dialog expands with options resembling the following screen shot.

Select Execute - send a request with your token to Vault.

You should now observe a response in the Responses section.

This section contains an example curl command line to make the same API request from a command line environment. It also displays the full request URL.

Next, the server response is shown with the response body as a JSON object and the response header values present along with response code and optional description. You can also download the complete server response data by selecting Download.

»/sys/mounts

The /sys/mounts API provides a listing of enabled secrets engines. Since the learn-ui-api policy you defined previously in this tutorial provides read capability for this API endpoint, you can try it in the API Explorer.

To quickly locate the endpoint in the list, use the search and enter sys/mount. This will narrow the results to entries containing the string "sys/mounts", including the first result, a GET for /sys/mounts.

Select the GET entry and then select Try it out; a dialog expands with options resembling the following screen shot.

Select Execute - send a request with your token to Vault.

Vault returns the response data and other helpful information in the Responses section.

This section contains an example curl command line to make the same API request from a command line environment. It also displays the full request URL.

Next, the server response is shown with the response body as a JSON object and the response header values present along with response code and optional description. You can also download the complete server response data by selecting Download.

You can scroll through the response data to learn more about the enabled secrets engines or you can also download the JSON file and use it programmatically; the downloaded filename takes the format response_<unix_timestamp>.json.

For example with a utility like jq, you can query the data later in an "offline" manner to learn about enabled secrets engines.

$ jq -r '.data | keys' response_1601311217499.json

Successful output example:

[
  "cubbyhole/",
  "identity/",
  "kv/",
  "sys/",
  "transit/"
]

»Next steps

You learned how to use the Vault API Explorer functionality within the UI and execute calls to different API endpoints. Continue with Next Steps for the conclusion of the Vault UI tutorial collection.

»Help and reference

  • Vault HTTP API documentation
  • Create Vault Policies


PreviousManage Secrets EnginesNextNext Steps
HashiCorp
  • System Status
  • Terms of Use
  • Security
  • Privacy
stdin: is not a tty