API Explorer in Vault UI

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"]
}

# 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"]
}

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.

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.

»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

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

Successful output example:

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

[
  "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 tutorials.

»Help and reference

• Vault HTTP API documentation
• Create Vault Policies