Rails secret_key_base: what breaks when you rotate it

Rotating secret_key_base in Rails invalidates sessions, encrypted and signed cookies, and Active Storage files that depend on it. Rotate it when you suspect exposure, not on a whim, and plan for the user impact before you deploy the change.

What it protects

The Rails security guide says the cookie session store encrypts session data with keys derived from secret_key_base. Signed and encrypted cookies use it too, with separate salts. So this one value sits under authentication state for the whole app.

Where it lives

The guide notes that in development and test, Rails derives it from the app name. In other environments it comes from the encrypted file config/credentials.yml.enc. The master key that decrypts that file must be stored outside the repository, for example in your deployment secret store.

You can generate a fresh value with bin/rails secret. Keep secrets long and random.

What breaks on rotation

According to the guide, rotating secret_key_base invalidates:

• sessions
• encrypted and signed cookies
• Active Storage files

In practice that means every user is logged out, remember-me tokens stop working, and links that relied on signed values stop validating. That is acceptable after a leak and annoying otherwise.

When to rotate

Rotate if the value may have been exposed. Examples: it was committed to a repository, printed in a log, shared in a chat, or a former employee still holds the master key. If you cannot rule out exposure, assume it happened.

Before you rotate

1. Announce a forced logout if you have a user base to warn.
2. Check what depends on signed values, such as email confirmation links and download URLs.
3. Confirm Active Storage impact in your setup before production.
4. Rotate the master key too if it was part of the exposure.
5. Verify new values deploy to every server at the same time, so users are not bounced between old and new.

Related hygiene

• Use separate salts for encrypted and signed cookies, as the guide says.
• Filter sensitive parameters out of logs with config.filter_parameters.
• Set config.force_ssl = true.

Quick check

Sources

• Securing Rails Applications

Last reviewed: 19 October 2026.