Key Tenant Secret Rotation
Key Tenant Secret Rotation is the Salesforce Shield Platform Encryption operation of generating a new tenant secret so it becomes the active key material, while the previous secret is archived and kept available to decrypt older data.
Definition
Key Tenant Secret Rotation is the Salesforce Shield Platform Encryption operation of generating a new tenant secret so it becomes the active key material, while the previous secret is archived and kept available to decrypt older data. Salesforce calls this key rotation because the new tenant secret derives new data encryption keys, and every write after the rotation uses them. The work happens in Setup under Encryption Settings, in the Key Management view, using the Generate Tenant Secret button.
Rotation by itself is fast and non-disruptive. New records encrypt under the new active secret, and reads of older records keep decrypting under the archived secret, so nobody notices a change. To move existing data onto the new key you run the background encryption service, which re-encrypts records under the active secret. The Status column in Key Management labels each secret Active, Archived, or Destroyed, and that lifecycle is the heart of the practice.
How tenant secret rotation actually works
The secret, the key, and where rotation fits
A tenant secret is one half of the recipe Salesforce uses to build a data encryption key. Salesforce combines your tenant secret with a per-release primary secret it holds, runs both through a key derivation function, and produces the key that encrypts your fields and files. You never see the derived key, and it is never written to disk in the clear. Because the derived key depends on the tenant secret, replacing the tenant secret produces fresh derived keys. That is exactly what rotation does. You generate a new tenant secret, Salesforce marks it Active, and from that moment new derivations use it. The old secret does not vanish. It moves to Archived status and stays usable for decryption, so data written under it still opens correctly. This split between an active secret for writing and archived secrets for reading is the design that lets you rotate often without breaking access to historical records. It also explains why rotation is cheap to trigger but only finishes its job once you re-encrypt the older data.
Active, Archived, and Destroyed statuses
Key Management shows every tenant secret with a Status of Active, Archived, or Destroyed. Active is the one secret currently deriving keys for new encryption. There is exactly one active secret per key type at a time. When you generate a replacement, the prior active secret becomes Archived. An archived secret cannot encrypt anything new, but it can still decrypt records that were written while it was active. That is why archived secrets matter: destroying one too early makes any data still depending on it unreadable, with no recovery path. Destroyed is the terminal state, and it is irreversible. You only destroy a secret after you are certain nothing depends on it, which in practice means after the background encryption service has re-encrypted all of that data under a newer secret. Salesforce keeps a record of destroyed secrets so you can see the history, but the key material itself is gone. Treat destruction as a deliberate cleanup step, never a routine part of each rotation cycle.
Generating the new secret
To rotate, you need the Manage Encryption Keys user permission, which is separate from the permission that turns encryption on for fields. In Setup you open Encryption Settings, go to the Key Management area, pick the key type you want to rotate (Data in Salesforce, the search index, Analytics, or the event bus, depending on what you encrypt), and click Generate Tenant Secret. Salesforce creates the new secret, sets it Active, and archives the old one in one step. The action takes seconds and needs no downtime window. Users keep working through it. One platform rule shapes your cadence: you can rotate a given key type as often as every 24 hours, but not more frequently than that. So a same-day mistake cannot be undone by immediately rotating again twice in a row within the window. For BYOK setups the flow differs slightly because you upload externally generated material instead of clicking Generate, but the result is identical: the newest material becomes active and the prior material is archived.
Why generating a secret is only half the work
A freshly generated secret protects new writes immediately, but it does nothing to the millions of records already encrypted under the old secret. Those records still depend on the now-archived secret. If you stop at generation, that archived secret stays in active use for all of its data forever, which quietly defeats the point of rotating. The fix is the background encryption service, sometimes called self-service background encryption or mass encryption. It walks your encrypted data and re-encrypts it under the current active secret, so the older secret is no longer needed. This service is asynchronous and can run for hours or longer depending on volume, and Salesforce limits it to once every 7 days per org. Plan around both facts. Schedule the synchronization for a quieter period, and remember you cannot fire it repeatedly to chase small changes. Many teams treat a rotation as a two-part task on the calendar: generate the secret today, then trigger the background encryption job and let it finish before considering the rotation complete.
A practical rotation cycle, start to finish
Picture a company with an annual rotation policy. In month one an admin with Manage Encryption Keys opens Key Management and clicks Generate Tenant Secret for Data in Salesforce. The new secret is Active in seconds, the old one is Archived, and overnight orders start encrypting under the new key. Nothing in the user interface changes for sales reps. A day later the admin opens the encryption statistics view and starts the background encryption service to re-encrypt last year of records under the new secret. The job runs over a weekend. Once it finishes, every active record depends on the new secret, and the archived secret is only holding any data the job could not reach, which the admin investigates. Months later, after confirming no data references the oldest secret, the team destroys it as a clean-up. The next year the cycle repeats. The whole pattern is generate, synchronize, verify, and only much later destroy. Each rotation bounds how much data any single key protects.
BYOK, Cache-Only Keys, and rotation cadence
Bring Your Own Key changes who creates the secret, not how rotation behaves. With BYOK you generate 256-bit key material in your own system, wrap it with a BYOK-compatible certificate, and upload it to Salesforce. Your most recent upload becomes the active tenant secret and earlier uploads are archived, mirroring the Salesforce-generated flow. To rotate, you upload new wrapped material on your schedule. The Cache-Only Key Service goes further: Salesforce never stores your key, it fetches the key from your external key service on demand and caches it briefly, so rotation means changing the key your service hands back. Choosing a cadence is a policy decision, not a platform one. Annual rotation is a common baseline for general business data, while regulated industries such as finance and healthcare often require quarterly or tighter. The platform supports anything down to the 24-hour floor. The most frequent rotation failure is not technical at all. It is simply forgetting to rotate, so document the cadence and audit against it.
How to rotate a tenant secret in Setup
Rotating a tenant secret is a Setup operation, not a record you fill in. You generate a new secret, then synchronize existing data. Both steps require the Manage Encryption Keys permission.
- Confirm your permission
Make sure your user has the Manage Encryption Keys permission. It is granted through a permission set or profile and is distinct from the permission that selects which fields are encrypted.
- Open Key Management
In Setup, go to Encryption Settings and open the Key Management view. Choose the key type you intend to rotate, such as Data in Salesforce, the search index, Analytics, or the event bus.
- Generate the new tenant secret
Click Generate Tenant Secret. Salesforce creates the secret, sets its Status to Active, and moves the previous secret to Archived. New writes immediately use the new key material.
- Synchronize existing data
Open the encryption statistics view and start the background encryption service. It re-encrypts older records under the active secret. The job is asynchronous and is limited to once every 7 days.
Tenant secrets are scoped by what they protect: Data in Salesforce, the search index, Analytics, and the event bus each rotate independently.
Salesforce-managed orgs click Generate Tenant Secret. BYOK orgs upload externally wrapped 256-bit key material; the newest upload becomes active.
You can rotate a given key type as often as every 24 hours. Choose a policy cadence, commonly annual or quarterly, and audit against it.
- Generating a secret alone does not re-encrypt old data. Without the background encryption job, the archived secret stays in active use for its records indefinitely.
- Never destroy an archived secret while any data still depends on it. Destruction is irreversible and makes that data permanently unreadable.
- The background encryption service runs at most once every 7 days, so batch your encryption changes rather than triggering it repeatedly.
- Back up tenant secrets before rotating or destroying anything, so you retain a way to decrypt data if something goes wrong.
Prefer this walkthrough as its own page? How to Key Tenant Secret Rotation in Salesforce, step by step
Trust & references
Cross-checked against the following references.
Straight from the source - Salesforce's reference material on Key Tenant Secret Rotation.
Hands-on resources to go deeper on Key Tenant Secret Rotation.
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 Key Tenant Secret Rotation involve in Shield Platform Encryption?
Q2. Why rotate the tenant secret on a regular cadence?
Q3. Should administrators destroy old tenant secrets right after rotation?
Discussion
Loading discussion…