Vault Associate Certification (Part 8): Be aware of the Vault API

Being aware of the Vault API make up the eight objective in the Vault certification journey. This objective covers the following sub-objectives:

• Authenticate to Vault via cURL
• Access Vault secrets via cURL

As is clear from the number of sub-objectives in this part this is not a huge topic. It is important to be aware of a few general things related to using the API that is implicitly handled for you when using the Vault CLI. You are not expected to be able to perform every common action using the API.

Authenticate to Vault via cURL

This sub-objective covers how to authenticate to Vault when running any operation that requires a token.

The Vault token must be provided as a header in all requests to Vault that requires authentication. There are two options for providing the token:

• As the X-Vault-Token HTTP header with a value of <token>.
• As the Authorization header with a value of Bearer <token>.

How do you obtain a token to begin with using the API? This depends on the authentication method you want to use. As an example, using the userpass auth method for a user named bob:

$ curl \
    --header "X-Vault-Token: $VAULT_TOKEN" \
    --request POST \
    --data '{"password": "S3cr3t"}' \
    http://127.0.0.1:8200/v1/auth/userpass/login/bob

Note that all requests are sent to <server url>:8200/v1/<path>.

The response from this request looks like the following:

{
    "request_id": "efa4b077-5820-1682-6c52-d30e8b48cccb",
    "lease_id": "",
    "renewable": false,
    "lease_duration": 0,
    "data": null,
    "wrap_info": null,
    "warnings": null,
    "auth": {
        "client_token": "hvs.CAESIPi7<truncated>Qza1ZVQ29LUGs",
        "accessor": "Y13YI0FyHxNm3zXl6i0OtpFI",
        "policies": [
            "default"
        ],
        "token_policies": [
            "default"
        ],
        "metadata": {
            "username": "bob"
        },
        "lease_duration": 2764800,
        "renewable": true,
        "entity_id": "cdb98f68-38b8-ecbb-7979-2ad1b9818f76",
        "token_type": "service",
        "orphan": true,
        "mfa_requirement": null,
        "num_uses":
        0
    }
}

In this example we also saw how the X-Vault-Token header is provided in the request.

Access Vault secrets via cURL

For this sub-section I assume you have a development server running with the key/value secrets engine (version 2) enabled at kv/. The specifics of how to write and read secrets from a secrets engine depends on what secrets engine you are using, read the API documentation for your secrets engine of choice.

Let us first write a new secret to database/password with some data:

$ curl \
    --header "X-Vault-Token: $VAULT_TOKEN" \
    --request POST \
    --data '{"data":{"password": "S3cr3t"}}' \
    http://127.0.0.1:8200/v1/kv/data/database/password

Notice how I write this data to kv/data/<my path>. The response to this request is:

{
    "request_id": "b9891d16-779e-af48-7e37-02deaf786e4d",
    "lease_id": "",
    "renewable": false,
    "lease_duration": 0,
    "data": {
        "created_time": "2023-09-11T15:47:09.14348Z",
        "custom_metadata": null,
        "deletion_time": "",
        "destroyed": false,
        "version": 1
    },
    "wrap_info": null,
    "warnings": null,
    "auth": null
}

Now we can read this data back:

$ curl \
    --header "X-Vault-Token: $VAULT_TOKEN" \
    --request GET \
    http://127.0.0.1:8200/v1/kv/data/database/password

The response is:

{
  "request_id": "af5770e1-3d10-f0be-5536-4b0ab25eafc2",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "data": {
      "password": "S3cr3t"
    },
    "metadata": {
      "created_time": "2023-09-11T15:47:09.14348Z",
      "custom_metadata": null,
      "deletion_time": "",
      "destroyed": false,
      "version": 1
    }
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null
}

We see that the response contains details about the request, details about the lease, and all the data and metadata.

Summary

This was a short post, but it is unlikely to be a big topic on the exam. Remember the following things and you should be good:

• The request URL has the format <server URL>:8200/v1/<path>.
• The token is provided in a header:
  • X-Vault-Token with the value of <token>, or
  • Authorization with the value of Bearer <token>.