Token vault design: separation of concerns

A token vault — the service that maps a payment token to a card number — is a small, boring piece of infrastructure with an outsized responsibility. The design choices made early are hard to reverse, and the common mistakes are consistent.

Written April 2026 from a set of platform reviews.

What the vault should do

• Map opaque tokens to card data.
• Enforce access control per calling service.
• Log every access with attribution.
• Rotate the encryption keys protecting stored data on a schedule.

That's it. It should not:

• Make authorization decisions.
• Enforce merchant business rules.
• Handle refunds or reversals.
• Route to schemes.

Everything else is a separate concern that will grow when its needs conflict with the vault's needs.

The common mistakes

• Vault does too much. The vault becomes the place where "we know the card so it's convenient" tasks accumulate. Every one of them expands the audit scope and the attack surface.
• Vault has too many callers. Twenty services can read the vault directly. Now the vault's access control is the perimeter for twenty services.
• Vault is not backed by an HSM. The stored keys are in an application configuration file, not a hardware security module. This works until the day someone with database access has a bad day.
• No detokenisation audit log. Every call to convert a token back to a PAN should be logged with caller identity. If you can't answer "who read this token in the last 24 hours", you have a vault-shaped problem.

What good looks like

A vault with one call pattern: give it a token, get back a redacted, purpose-scoped card view. Full PAN only leaves the vault at the moment of authorization dispatch, and never to a caller that will store it. This is boring engineering. It's also the difference between a defensible design and one that becomes an incident.