Vault Token Accessor in Practice and on the Exam: Audit and Revoke Tokens the Fast Way

A Token Accessor is an identifier that lets you look up, renew (when renewable), or revoke a token without ever exposing the token value itself. It is the linchpin of audit and incident response.

This article covers the link to audit logs, the revocation flow, the policy capabilities you need, and the operational pitfalls, with concrete examples throughout.

Token Accessor Basics: What It Can and Cannot Do

Vault generates a short identifier called an accessor for every token. Accessors cannot be used to authenticate, but through admin APIs they can look up, renew (when the token is renewable), and revoke the target token. That lets you run operations without ever touching the raw token value.

From an audit perspective, request and response audit entries include the accessor, so once the SOC pinpoints a suspicious request it can revoke immediately using the accessor as the key. Accessors are unique, bound to the token's lifecycle, and become invalid when the token is revoked.

• What you can do: lookup-accessor, renew-accessor (renewable tokens only), revoke-accessor.
• What you cannot do: authenticate with the accessor, read secrets, or recover the token value.
• Because it appears in audit logs, the accessor doubles as a hub for investigation and revocation.

Using Accessors in Audit Logs: From Ingest to Revocation

Vault's audit devices record post-authentication request information as JSON. Because the accessor is included, you can trace back without touching token strings. Audit devices HMAC sensitive fields, and depending on configuration the accessor itself may also appear as an HMAC (for example, hmac-sha256:...).

In production, standardizing the flow detect suspicious requests in your SIEM → extract the accessor → look up with an admin token → revoke-accessor if needed dramatically speeds up response.

• Identify the token via auth.accessor in audit entries (type=request/response).
• The client_token is HMAC'd, but the accessor still lets you identify and revoke.
• Even with multiple audit devices enabled simultaneously, the accessor consistently points to the same token.

Signal flow from audit to revocation

Example of extracting an accessor from audit logs (JSON Lines)

tail -f /var/log/vault_audit.log | jq -r 'select(.type=="request") | .auth.accessor' | grep -v null

Revoke, Look Up, and Renew Tokens via the Accessor

Accessors sit at the core of incident response. Confirm the target first with lookup-accessor, then revoke-accessor immediately if the token is unwanted or suspicious. For renewable tokens, renew-accessor can extend the TTL.

All three endpoints use HTTP POST (write) and require the right policy capabilities (update, and sometimes sudo). A request against an unknown accessor returns a 404-equivalent error.

• Lookup: /v1/auth/token/lookup-accessor
• Renew: /v1/auth/token/renew-accessor
• Revoke: /v1/auth/token/revoke-accessor

A minimal cURL playbook for accessor operations

# 管理トークンを使う
export VAULT_ADDR=https://vault.example.com
export VAULT_TOKEN=s.xxxxx

# 1) Lookup: アクセサからメタデータを確認
curl -s \
  --header "X-Vault-Token: $VAULT_TOKEN" \
  --request POST \
  --data '{"accessor":"h1234567-..."}' \
  $VAULT_ADDR/v1/auth/token/lookup-accessor | jq

# 2) Renew: 更新可能な場合にTTL延長(3600秒)
curl -s \
  --header "X-Vault-Token: $VAULT_TOKEN" \
  --request POST \
  --data '{"accessor":"h1234567-...", "increment": "3600"}' \
  $VAULT_ADDR/v1/auth/token/renew-accessor | jq

# 3) Revoke: 即時無効化(子トークンも失効)
curl -s \
  --header "X-Vault-Token: $VAULT_TOKEN" \
  --request POST \
  --data '{"accessor":"h1234567-..."}' \
  $VAULT_ADDR/v1/auth/token/revoke-accessor

Required Capabilities and Policy Design Tips

All accessor endpoints require write (update) capability and amount to token management, so limit them to operations (duty) tokens and automation roles rather than ordinary users. revoke-accessor in particular has a wide blast radius, so fine-grained guardrails are essential to prevent unintended revocation.

When using Enterprise Namespaces, an accessor is valid only within that namespace's context. Operations against the wrong namespace will fail, so operational scripts must always set the namespace header or environment variable explicitly.

• Least privilege: scope lookup/renew to specific tokens; grant revoke only to the operations team.
• In your policy, grant update (and sudo when required) on the target paths under auth/token/*.
• In automation, double-check with lookup before acting and revoke only on matching conditions.

Example policy (HCL): a role dedicated to accessor operations

path "auth/token/lookup-accessor" {
  capabilities = ["update", "sudo"]
}
path "auth/token/renew-accessor" {
  capabilities = ["update", "sudo"]
}
path "auth/token/revoke-accessor" {
  capabilities = ["update", "sudo"]
}
# 追加の安全策: 対象を運用で許可するprefix等に制限する場合は、
# Sentinel/OPA等のポリシー統制と組み合わせる。

Operational Patterns and Pitfalls: How Not to Fail

Accessors are useful but not omnipotent. renew-accessor will fail on non-renewable tokens. lookup and revoke will both error against an already-revoked accessor because the target no longer exists. Audit log lag and concurrent revocations frequently make accessors invisible.

Mind the parent-child relationship: revoking a parent token cascades to children. Verify the blast radius up front by running lookup to check policies, display_name, creation_path, ttl, and so on, and adopt a staged revocation strategy (narrowing the scope) when needed.

• renew-accessor is renewable-tokens only; non-renewable or fixed-TTL tokens return an error.
• Even when an accessor is unknown (404 etc.), keep the audit timeline consistent and recompute on the SIEM side.
• revoke-accessor also revokes child tokens; always confirm the blast radius first.
• Make automation idempotent: lookup to confirm existence → check conditions → revoke, in that order.
• Depending on the audit device's HMAC settings, the displayed accessor may be hashed.

Associate Exam Checkpoints and Comparison Table

On the exam, the high-frequency points are the accessor's purpose (lookup / renew / revoke), the fact that it cannot authenticate, its role in audit logs, and the effect of revoke-accessor (children included). Memorize the endpoint names and required capabilities (update, and sometimes sudo) precisely.

The table below summarizes the differences against concepts that are easy to confuse. In practice, the rule of thumb accessor for audit, token value for authentication helps prevent mis-operations.

• The accessor is the key for operations and audit; the token value is the key for authentication.
• lookup, renew, and revoke are all POST and require update capability.
• revoke-accessor is immediate and also sweeps up child tokens.

Check Your Understanding

Frequently Asked Questions