Token-Scoped Temporary Storage with Vault Cubbyhole

Cubbyhole is a built-in Vault secrets engine that gives every token its own private namespace. When the token is revoked, the contents disappear, making it a great fit for short-lived secret storage and handoff.

This article covers how Cubbyhole works, its lifecycle, how it pairs with response wrapping, hands-on workflows, operational constraints, and the gotchas commonly tested on the exam.

Cubbyhole Basics: A Private Vault Per Token

Cubbyhole is a secrets engine that ships with Vault by default. It gives each access token its own dedicated storage area. Values written by one token can only be read by that same token. There is no way to grant access from another token or via policy delegation.

The API is simple, with no versioning or metadata management. TTL is not attached to the secret itself; it follows the lifecycle of the associated token. When the token expires or is revoked, the Cubbyhole data is automatically purged.

• Default mount path: cubbyhole/
• Access boundary: per-token (no access from other tokens)
• Use cases: startup bootstrapping, short-lived token staging, and a scaffold for one-way secure handoff

Basic CLI operations

vault write cubbyhole/bootstrap token=child-abc note="startup"
vault read cubbyhole/bootstrap
vault delete cubbyhole/bootstrap

Security Properties and Lifecycle: TTL, Revocation, and Inheritance

The availability of Cubbyhole data tracks the associated token, not the stored entry. Renewing the token preserves the data, while revoking it wipes the data immediately. This prevents secrets from being left behind.

Pay attention to the parent-child token relationship. Child tokens have their own Cubbyhole, isolated from the parent. When parent revocation cascades to children, the child tokens are invalidated too, and their Cubbyhole contents become inaccessible.

• Token renewal preserves Cubbyhole contents
• Token revocation or expiry destroys the contents
• Policy cannot grant access to another token's Cubbyhole
• Behavior is consistent regardless of HA setup or storage backend (per Vault's design)

Token renewal/revocation and Cubbyhole behavior (CLI example)

# Issue a token (example)
vault token create -ttl=1h -policy=default -format=json | jq -r .auth.client_token > parent.token

# Issue a child token (within the parent's rights)
VAULT_TOKEN=$(cat parent.token) vault token create -ttl=15m -format=json | jq -r .auth.client_token > child.token

# Write to the cubbyhole as the child
VAULT_TOKEN=$(cat child.token) vault write cubbyhole/boot key=value

# Revoking the parent also invalidates its children, cutting off access
vault token revoke $(cat parent.token)

# Reads with child.token are expected to fail from here on
VAULT_TOKEN=$(cat child.token) vault read cubbyhole/boot

Hands-On: Token-Scoped Temporary Storage Flow

Cubbyhole shines for bootstrapping: a freshly started process uses a least-privilege child token to receive temporary config or a follow-on retrieval token. The distributor writes to a location only the target process's token can see, and the process retrieves and discards it right after startup. That pattern is safe.

Direct Cubbyhole reads and writes are NOT one-time. If you need to guarantee single-use behavior, use response wrapping (covered below).

• Issue a child token per process
• Keep child token TTLs short and renew as needed
• After retrieval, clean up via explicit delete or token revocation

Temporary storage via CLI / HTTP API

# CLI: write and read with the child token
VAULT_TOKEN=$CHILD_TOKEN vault write cubbyhole/config db_user=app db_pass=s3cr3t
VAULT_TOKEN=$CHILD_TOKEN vault read cubbyhole/config

# HTTP API: write
curl \
  -H "X-Vault-Token: $CHILD_TOKEN" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{"db_user":"app","db_pass":"s3cr3t"}' \
  $VAULT_ADDR/v1/cubbyhole/config

# HTTP API: read
curl -H "X-Vault-Token: $CHILD_TOKEN" $VAULT_ADDR/v1/cubbyhole/config

Response Wrapping and Cubbyhole: Secure One-Time Handoff

Response wrapping seals a Vault response inside a wrapping token so it can be retrieved exactly once. Internally, Cubbyhole is used, and if the token is not unwrapped within wrap-ttl, the contents are automatically destroyed. This lets you ship only a token instead of the secret itself.

The producer attaches -wrap-ttl to any read operation, and the consumer calls vault unwrap or POSTs to /sys/wrapping/unwrap with the wrapping token. On a successful unwrap, the contents are returned and the token is invalidated.

• Keep wrap-ttl short (e.g., 60s to 5m)
• Wrapping tokens are single-use. Enable audit logging to watch for leaks
• Decide your retry strategy in advance (re-wrap on failure)

Response wrapping handoff

Response wrapping example

# Wrap when reading secret data (a KV v2 secret, for example)
# The point is that whatever the engine, the response becomes a wrapping token
vault kv get -wrap-ttl=60s kv/app/api
# Output: wrapping_token=... (usable exactly once)

# Receiver: unwrap to get the contents (the token is then dead)
VAULT_TOKEN=$WRAPPING_TOKEN vault unwrap

# The same over the HTTP API
curl -s -H "X-Vault-Token: $VAULT_TOKEN" \
  "$VAULT_ADDR/v1/kv/data/app/api?wrap_ttl=60s"
# auth.client_token in the response JSON is the wrapping token

# unwrap
curl -s -H "X-Vault-Token: $WRAPPING_TOKEN" \
  -X POST "$VAULT_ADDR/v1/sys/wrapping/unwrap"

Operations and Constraints: What to Store and What Not To

Cubbyhole is ideal for lightweight temporary storage but unsuitable for large binaries or long-lived config files. Size limits depend on the underlying storage and operational policy, so as a rule, target small secrets and tokens only.

If audit logging is enabled, access under cubbyhole/ is also recorded (the data itself is masked). This is useful for leak detection and monitoring how wrapping tokens are handled.

• Default policy: small values, short-lived, disposable
• Clean up via explicit delete or token revocation when no longer needed
• Use other engines like KV v2 for long-term storage or sharing

Make cleanup explicit

# Delete it once you have taken it out
VAULT_TOKEN=$CHILD_TOKEN vault delete cubbyhole/config

# Revoke the child token once it has served its purpose
vault token revoke $CHILD_TOKEN

Exam Prep: Common Misconceptions and Terminology

Cubbyhole is private storage attached to a token. It is not designed to be shared with others via policy. Do not confuse it with the sharing and versioning model of KV v2.

Response wrapping is the mechanism that delivers one-time retrieval, and you should remember that it uses Cubbyhole internally. Contents are destroyed on wrap-ttl expiry or on a successful unwrap.

• Keywords: per-token isolation, deleted on revoke, wrap-ttl, unwrap = single-use
• Design choices: KV for sharing/long-term, wrapping for single-use delivery, Cubbyhole for short-lived same-token handoff
• Gotcha: putting data in Cubbyhole alone does not make it single-use (only wrapping does)

One-liner sanity check

# Only this token should be able to read its cubbyhole
VAULT_TOKEN=$OTHER_TOKEN vault read cubbyhole/boot  # -> expected to fail with a permission error

Check Your Understanding

Frequently Asked Questions