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 ofBearer <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 ofBearer <token>
.
-
Top comments (0)