Create and store secrets in HCP Vault Dedicated

8min
|
HCP
Vault

One of the core features of Vault is the ability to read and write arbitrary secrets securely. Vault encrypts secrets when written to the backend storage. Therefore, the backend storage mechanism never sees the unencrypted value and doesn't have the means necessary to decrypt it without Vault.

HashiCups wants to store application secrets such as API keys, passwords, and certificates in HCP Vault Dedicated. In this tutorial, Oliver from HashiCups learns how to create and store secrets using the Key/Value (K/V) secrets engine in HCP Vault Dedicated.

Prerequisites

Completed the Create a Vault Cluster on HashiCorp Cloud Platform (HCP) tutorial.
Completed the Access your HCP Vault Dedicated cluster tutorial.

Key/Value secrets engine

The Key/Value v2 secrets engine is a generic key-value store used to store arbitrary secrets within the configured physical storage for Vault.

The Key/Value secrets engine has version 1 and 2. The difference is that v2 provides versioning of secrets, while v1 does not.

Use the vault kv <subcommand> [options] [args] command to interact with the K/V secrets engine.

Available subcommands:

Subcommand	kv v1	kv v2	Description
delete	x	x	Delete versions of secrets stored in K/V
destroy		x	Permanently remove one or more versions of secrets
enable-versioning		x	Turns on versioning for an existing K/V v1 store
get	x	x	Retrieve data
list	x	x	List data or secrets
metadata		x	Interact with Vault's Key-Value storage
patch		x	Update secrets without overwriting existing secrets
put	x	x	Sets or updates secrets (this replaces existing secrets)
rollback		x	Rolls back to a previous version of secrets
undelete		x	Restore the deleted version of secrets

Enable secrets engine

(Persona: operations)

Before teams at HashiCups can write secrets to HCP Vault, Oliver must enable the key/value v2 secrets engine. You enable a secrets engine in a specific namespace. The secrets you create in the admin namespace are not accessible from other namespaces by default.

In the Vault UI, set the current namespace to admin/.
Click Secrets.
Click + Enable new engine.
Select KV from the list, you are routed to the next screen.
Enter secret in the Path field.
Click Enable Engine to complete.

If you did not set the VAULT_ADDR, VAULT_NAMESPACE, and VAULT_TOKEN environment variables, refer to the steps in the Create a Vault Cluster on HCP tutorial.

Verify that the VAULT_NAMESPACE environment variable is set to admin.
```
$ echo $VAULT_NAMESPACE
admin
```
If not, be sure to set it before you continue.
```
$ export VAULT_NAMESPACE=admin
```

Enable the key/value v2 secrets engine (kv-v2) at secret/.

$ vault secrets enable -path=secret kv-v2
Success! Enabled the kv-v2 secrets engine at: secret/

Each API request requires the token and Vault address. If you did not set the VAULT_ADDR and VAULT_TOKEN environment variables, refer to the steps in the Create a Vault Cluster on HCP tutorial.

Enable KV v2 at secret/.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
    --header "X-Vault-Namespace: admin" \
    --request POST \
    --data '{ "type": "kv-v2" }' \
    $VAULT_ADDR/v1/sys/mounts/secret

NOTE: Instead of passing the target namespace using the X-Vault-Namespace header, you can specify the namespace in the API endpoint, /admin/sys/mounts/secret. In that case, the cURL command becomes:

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
    --request POST \
    --data '{ "type": "kv-v2" }' \
    $VAULT_ADDR/v1/admin/sys/mounts/secret

Add secrets to Vault

(Persona: operations)

Now that you have enabled the KV secrets engine, you can write secrets to Vault. Vault allows you to create different paths. For example you can have one path for the ops team, with secrets they need access to, and another path for the development team with different secrets.

In the Vault UI, set the current namespace to admin/.
Click Secrets.
Click secret/. This is the secrets engine you enabled earlier in the tutorial.
Click + Create secret.
Enter dev/database in the Path for this secret textbox.
Enter username in the Secret data key field.
Enter database-user in the Secret data value textbox.

If you did not set the VAULT_ADDR, VAULT_NAMESPACE, and VAULT_TOKEN environment variables, refer to the steps in the Create a Vault Cluster on HCP tutorial.

Verify that the VAULT_NAMESPACE environment variable is set to admin.
```
$ echo $VAULT_NAMESPACE
admin
```
If not, set it before you continue.
```
$ export VAULT_NAMESPACE=admin
```

List the available secrets engines.

$ vault secrets list
Path               Type                 Accessor                      Description
----               ----                 --------                      -----------
agent-registry/    ns_agent_registry    ns_agent_registry_9527298a    agent registry
cubbyhole/         ns_cubbyhole         ns_cubbyhole_88274a41         per-token private secret storage
identity/          ns_identity          ns_identity_4d08b59d          identity store
secret/            kv                   kv_b7772333                   n/a
sys/               ns_system            ns_system_04f03953            system endpoints used for control, policy and debugging

You can see the secrets engine you enabled earlier in the tutorial at the path secret/.

Write a secret with the key username and a value of database-user.

$ vault kv put secret/dev/database username="database-user"
====== Secret Path ======
secret/data/dev/database

======= Metadata =======
Key                Value
---                -----
created_time       2026-09-28T16:00:45.522415012Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            1

Each API request requires the token and Vault address. If you did not set the VAULT_ADDR and VAULT_TOKEN environment variables, refer to the steps in the Create a Vault Cluster on HCP tutorial.

List the available secrets engines.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
    --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
    --request GET \
    $VAULT_ADDR/v1/sys/mounts | jq

Example output:

...snip...
    "secret/": {
      "accessor": "kv_b7772333",
      "config": {
        "default_lease_ttl": 0,
        "force_no_cache": false,
        "listing_visibility": "hidden",
        "max_lease_ttl": 0
      },
      "deprecation_status": "supported",
      "description": "",
      "external_entropy_access": false,
      "local": false,
      "options": {
        "version": "2"
      },
      "plugin_version": "",
      "running_plugin_version": "v0.26.3-0.20260626165612-824fb96aa7a8+builtin",
      "running_sha256": "",
      "seal_wrap": false,
      "type": "kv",
      "uuid": "0fcfb448-ae6d-bc36-f2d6-552c7f6e00ea"
    }
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null,
  "mount_type": "ns_system"
}

You can see the secrets engine you enabled earlier in the tutorial at the path secret/.

Write a secret with the key username and a value of database-user.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
   --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
   --request POST \
   --data '{"data": {"username": "database-user"}}' \
   $VAULT_ADDR/v1/secret/data/dev/database

Example output:

{
  "request_id": "aa643267-8a75-4f16-9e6c-b8995d50f0cf",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "created_time": "2026-09-28T16:12:22.10597175Z",
    "custom_metadata": null,
    "deletion_time": "",
    "destroyed": false,
    "version": 1
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null,
  "mount_type": "kv"
}

Knowledge checks

A quiz to test your knowledge.

What is the default namespace used when you first access your HCP Vault Dedicated cluster?
🔘 root/
🔘 system/
🔘 admin/
🔘 default/
❌ root/
❌ system/
✅ admin/
❌ default/
What is the difference between Key/Value v1 and Key/Value v2 secrets engines in Vault?
🔘 KV v2 provides versioning of secrets, while KV v1 does not.
🔘 KV v1 supports higher throughput than KV v2.
🔘 KV v2 encrypts secrets while KV v1 stores them in plain text.
🔘 KV v1 allows secret destruction, while KV v2 does not.
✅ KV v2 provides versioning of secrets, while KV v1 does not.
❌ KV v1 supports higher throughput than KV v2.
❌ KV v2 encrypts secrets while KV v1 stores them in plain text.
❌ KV v1 allows secret destruction, while KV v2 does not.
What command would you use in the Vault CLI to store a secret with key db-password and value s3cr3t! at the path secret/database?
vault kv put secret/database db-password="s3cr3t!"

Summary

In this tutorial Oliver enabled one of Vault's secrets engines, giving you an introduction to the key/value v2 secrets engine. After Oliver enables the secrets engine, they write a secret for the development team to use. To learn more about the K/V secrets engine, follow the Versioned Key/Value secrets engine tutorial.

Next steps

Oliver enabled the key/value v2 secrets engine and created a secret in HCP Vault. To fully take advantage of HCP Vault, following security best practices, Oliver needs to learn how to author policies to manage access to Vault resources at different paths.

Enable multi-tenancy

Manage access to secrets