DEV Community

Cover image for Vault Associate Certification (Part 8): Be aware of the Vault API
Mattias Fjellström
Mattias Fjellström

Posted on • Originally published at mattias.engineer

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:

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
Enter fullscreen mode Exit fullscreen mode

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
    }
}
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
}
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
}
Enter fullscreen mode Exit fullscreen mode

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>.

Top comments (0)