Key Management
Key Management in Salesforce is the set of administrative operations that control the cryptographic key material behind Shield Platform Encryption.
Definition
Key Management in Salesforce is the set of administrative operations that control the cryptographic key material behind Shield Platform Encryption. Those operations include generating a new tenant secret, importing customer-supplied key material for Bring Your Own Key, configuring an external or Cache-Only key service, rotating the active secret, exporting secrets for backup, and destroying retired or compromised secrets. The work happens on the Key Management page inside Encryption Settings in Setup.
The platform handles the cryptographic mechanics for you. It derives data encryption keys, generates initialization vectors, and produces ciphertext without exposing those details to the administrator. Your job is the lifecycle: deciding when a key rotates, who is allowed to touch it, and proving to auditors that policy was followed. Because destroying a key can make the data under it permanently unreadable, key management is the highest-stakes administrative responsibility in any org that runs Shield.
How key material moves through its lifecycle
The derived-key model behind every operation
Understanding key management starts with understanding what a tenant secret actually does. Salesforce never stores a single data encryption key on disk. Instead it combines your tenant secret with a per-release primary secret, then runs both through a key derivation function to produce the data encryption key on demand. That derived key lives only in an encrypted cache, never in a database column or a backup file. When an operation needs to encrypt or decrypt a field, the platform derives the key, uses it, and discards it. This design is why rotation is non-disruptive and why destruction is final. Rotating generates a fresh tenant secret, so new writes derive a new key, while older data still derives its key from the archived secret. Destroying a tenant secret removes the one input that makes derivation possible. Without that secret, the data encryption key can never be reconstructed, and the ciphertext stays locked. Every operation on the Key Management page is really an operation on this derivation chain, not on the encrypted records themselves.
Tenant secret states you manage
A tenant secret moves through a small set of states, and the Key Management page shows them per key type. A newly generated secret becomes Active, meaning it is the secret used to derive keys for new encryption. When you rotate, the prior Active secret becomes Archived. Archived secrets are not dead weight. They still derive the keys that decrypt data written while they were active, so older records stay readable. A Destroyed secret is permanently invalidated, and any data that depended only on it becomes unrecoverable. Most orgs keep several Archived secrets at once, one for each rotation cycle, until they re-encrypt older data forward onto the current key. The mistake to avoid is treating Archived as a synonym for unused. If even one field somewhere still resolves to an archived secret, destroying that secret loses the field. The state column is your map. Read it before any destructive action, and confirm that nothing still resolves to the secret you intend to remove.
Generation paths: Salesforce-managed, BYOK, and Cache-Only
How a secret comes into existence depends on the model you chose. With Salesforce-managed keys, you click Generate Tenant Secret and the platform creates the material for you, with no external system involved. Bring Your Own Key gives you more control. You generate the key material outside Salesforce, often in a hardware security module, wrap it under a Salesforce-provided public key, and upload it. The platform stores your supplied material rather than generating its own. The third path keeps key material off Salesforce entirely. With the External Key Management service or the Cache-Only Key Service, your secret lives in a repository you control. Salesforce fetches it on demand over a channel you configure, holds it only in the encrypted cache, and never persists it in any system of record or backup. The Cache-Only cache flushes on a regular cycle, after which the platform re-fetches from your key service. Each path trades convenience against control, and the Key Management page presents the right operations for whichever one your org runs.
Rotation and re-encrypting older data
Rotation is the routine you will run most often. Generating a new tenant secret makes it Active, and the previous secret moves to Archived automatically. New writes immediately use the new material. There is no downtime and no need to pause traffic. Many compliance regimes require rotation on a fixed cadence, annually for a lot of financial-services policies and more often for stricter ones. Rotation alone does not touch data already in the database. That older data still derives its key from the now-archived secret. To fully retire an old secret, you re-encrypt the affected data forward using the background synchronization process, which walks your encrypted fields and rewrites them under the current active key. Only after that completes can the old secret be safely destroyed, because nothing resolves to it anymore. Note two platform limits worth planning around: customer-supplied key material can be uploaded at most once every 24 hours in production, and freshly generated database key material may not be used for new derivations for up to 24 hours under the key backup policy.
Destruction, backup, and the recovery window
Destroying a tenant secret is the one operation with no undo from Salesforce. Once a secret is destroyed, Salesforce cannot recover it, and neither can you unless you exported a copy first. This is deliberate. It lets an organization prove to an auditor that it can render its own data unreadable on demand, the cryptographic-shredding control some regulations expect. The practical safety net is backup. Before any destructive work, export your tenant secrets and store them somewhere safe and separate. If you later destroy a secret and discover data still depended on it, importing the exported secret back into the org makes that data readable again. Salesforce is explicit that you are solely responsible for backing up keys, and that it cannot help with deleted, destroyed, or misplaced material. Treat destruction as a two-step gate: confirm via the synchronization status that no data resolves to the secret, and confirm a verified backup exists. Skipping either step turns a routine cleanup into permanent data loss.
Permissions, MFA, and the audit trail
Every operation on the Key Management page is gated by the Manage Encryption Keys permission. Because that permission can lead to irreversible loss, treat it more carefully than almost any other. Assign it to a small, named group of administrators, review the assignment on a regular schedule, and remove it from anyone who no longer needs it. A compromised account that holds this permission can do unrecoverable damage, so Salesforce lets you require multi-factor authentication specifically for key management actions. Turn that on. Accountability comes from the Setup Audit Trail, which records key events such as generation, rotation, archiving, and destruction, along with the user who performed each one. Compliance teams rely on these entries as evidence that rotation policy was honored and that destructive actions were authorized. If your retention requirement is longer than the trail keeps by default, export the records to an external system. Document, in writing, which named individuals are authorized for each operation type, then use the audit trail to confirm reality matches the policy.
How to rotate your tenant secret
Rotating your tenant secret on a schedule is the core key-management routine. The steps below cover generating a new active secret, then re-encrypting older data so the previous secret can eventually be retired. Shield Platform Encryption must already be enabled and you need the Manage Encryption Keys permission.
- Open Key Management
In Setup, enter Platform Encryption in the Quick Find box, then select Encryption Settings. Confirm encryption is enabled, then open the Key Management page where each key type and its current secret state are listed.
- Generate a new tenant secret
Choose the key type you want to rotate, then click Generate Tenant Secret (or import your wrapped material for a BYOK org). The new secret becomes Active and the previous one moves to Archived automatically.
- Re-encrypt existing data
From Encryption Settings, run the background synchronization to re-encrypt already-encrypted fields under the new active key. Monitor its status, because older data keeps resolving to the archived secret until this finishes.
- Back up, then retire the old secret
Export your tenant secrets and store them safely. Once synchronization confirms no data resolves to the archived secret, you may archive or destroy it per your retention policy.
Rotate the right material. Data in Salesforce, search index, analytics, and event bus can use distinct key types, each rotated on its own.
Required for every operation here. Grant it to a small named group and pair it with required multi-factor authentication for key management.
Customer-supplied key material can be uploaded at most once every 24 hours in production and Developer Edition orgs, and every 4 hours in sandboxes.
Newly generated database key material may not be used for new derivations for up to 24 hours under the key backup policy. Plan rotation windows around it.
- Rotation does not re-encrypt existing data. Without running synchronization, the previous secret stays in use indefinitely and cannot be safely destroyed.
- Destroying a secret is permanent. Salesforce cannot recover it, and unbacked-up data under it is lost forever. Always export secrets first.
- Archived does not mean unused. If any field still resolves to a secret, destroying it loses that field. Confirm via synchronization status before removing.
- Over-assigning Manage Encryption Keys is the leading risk. A single compromised holder can destroy keys, so audit the permission and require MFA.
Prefer this walkthrough as its own page? How to Key Management in Salesforce, step by step
Trust & references
Cross-checked against the following references.
- Key Management and RotationSalesforce
- Rotate Your Encryption Key MaterialSalesforce
Straight from the source - Salesforce's reference material on Key Management.
- Key Management and RotationSalesforce
- Bring Your Own Key (BYOK)Salesforce
Hands-on resources to go deeper on Key Management.
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. What does the Key Management surface let Shield administrators do?
Q2. Why is destroying a tenant secret the highest-stakes Key Management operation?
Q3. How should the Manage Encryption Keys permission be governed given its sensitivity?
Discussion
Loading discussion…