Vault Associate Certification (Part 8): Be aware of the Vault API
Tags: vault, hashicorp, security, learning
Published: 2023-09-11 16:02:41

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](#authenticate-to-vault-via-curl)
- [Access Vault secrets 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`:

```console
$ 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:

```json
{
    "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:

```console
$ 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:

```json
{
    "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:

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

The response is:

```json
{
  "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>`.