# Vault & Credential Handling (/docs/trust/vault)



Third-party tokens (CAPI access tokens, OAuth access/refresh tokens,
webhook signing secrets, etc.) are stored in the **Layers credential
vault** — encrypted at rest with a column-level secret store and
accessible only through an internal privileged interface, never from
the public API surface.

## Lifecycle [#lifecycle]

1. You paste a token into the Layers UI (HTTPS).
2. The partner API writes the plaintext into the vault and receives a
   `vault_id` (UUID).
3. Only the `vault_id` is stored on the referencing row (e.g.
   `project_layers.config.capi.access_token_vault_id`,
   `api_keys.signing_secret_vault_id`,
   `webhook_endpoints.secret_vault_id`).
4. The raw token is never returned back to the app after insert.

When the CAPI relay (or any downstream worker) needs the token:

1. Read the `vault_id` off the config row.
2. Request the token through the internal vault interface.
3. Receive the decrypted plaintext (held in process for the request
   lifetime, not logged).
4. Use it to sign the outbound call.

## What's in the vault (examples) [#whats-in-the-vault-examples]

* Meta CAPI access tokens.
* TikTok Events API access tokens.
* OAuth tokens for connected ads / social accounts.
* Partner API key hashes — actually `bcrypt`-hashed, not vaulted
  (different mechanism; still reversibility-proof).
* Webhook signing secrets (partner-visible outbound webhooks).

## What's NOT in the vault [#whats-not-in-the-vault]

* End-user tokens / identifiers.
* Layers-internal infrastructure secrets (those live in a separate
  internal secret manager, not partner-accessible).
* Anything shipped in a client bundle (build-time public values are by
  definition not secret).

## Rotation [#rotation]

When you regenerate a token upstream (e.g., rotate a Meta CAPI token):

1. Paste the new token into the Layers UI.
2. The vault entry is rotated in place — the `vault_id` stays stable;
   existing references on other rows don't need to update.

## Caveats [#caveats]

* Encryption keys are Layers-managed. Customer-managed keys (CMEK /
  BYOK) aren't available today.

## Audit [#audit]

Vault access is logged at the infrastructure level. Engineering
break-glass access to production is scoped and audited.