Rails Secret Key Base Generator

Every Rails app needs one long, random string before it can sign a single cookie, and a Rails secret key base generator is the quickest way to get it: run one command, copy the output, and keep it out of your repository. This guide shows how to generate a secret_key_base, where Rails reads it from in every environment, and how to replace it safely if it ever leaks.

What the Rails secret_key_base does for your application

The secret_key_base is the root value your application uses to derive every other key it needs. Rails feeds it into a key generator, and that generator produces the keys used by each ActiveSupport::MessageVerifier and ActiveSupport::MessageEncryptor in your app, including the ones that sign and encrypt cookies. The key generator itself, ActiveSupport::KeyGenerator, takes the secret_key_base and a salt and returns a derived key. If the value is weak, guessable or public, every signature built on top of it is weak too.

Think of it as the salt and seed for your application's cryptography. It does not encrypt your database and it is not a password for any user. It is the shared secret that lets your server recognise its own signed cookies and reject anything that has been altered in transit.

Signed cookies, sessions and the message verifier

When a visitor logs in, Rails stores the session in a cookie. The message verifier attaches a signature derived from the secret key base, so tampering with the cookie breaks the signature and the request is treated as invalid. That signature protects the integrity of the data; the message encryptor goes one step further and encrypts the contents so the visitor cannot read them either.

• Signed cookies stay readable but cannot be modified without the secret_key_base.
• Encrypted cookies are unreadable and tamper-proof, and Rails uses them for the session by default.
• Any feature built on a message verifier, such as password reset tokens or Active Storage URLs, depends on the same key.
• Rotating the key in a running application invalidates every signature issued before the change.

Why a weak secret key is dangerous

A short or dictionary-based secret key opens your application to dictionary attacks: someone who sees a signed cookie can try guesses offline until one reproduces the signature. A random value of 128 hex characters makes that guessing infeasible. Anyone who obtains the real value, for example from a public repository, can forge sessions and impersonate users, so treat it as sensitive as a database password.

Using a Rails secret key base generator from the command line

You do not need a website to generate a Rails secret key. Rails ships with a generator, and Ruby's standard library does the same job. Both rely on SecureRandom, which draws from the operating system's cryptographically secure random source. Looking to generate a random token? It works entirely in your browser and takes only a few seconds.

Using bin/rails secret

Inside your project, the built-in command prints a fresh randomly generated value and exits:

bin/rails secret

Older tutorials mention rake secret, which did the same thing before the Rails command line absorbed it. On a modern app, prefer bin/rails secret; if your project still uses Bundler wrappers, bundle exec rails secret works as well, and legacy scripts may call bundle exec rake secret. The output is a 128-character hexadecimal string, which equals 64 random bytes.

Generating a key with SecureRandom or OpenSSL

If you are outside a Rails project, such as inside a Docker build step or a deployment script, call Ruby directly or use OpenSSL:

ruby -rsecurerandom -e 'puts SecureRandom.hex(64)'
openssl rand -hex 64

Both commands produce the same kind of value as the Rails task. The Rails source for the task is only a few lines that require SecureRandom and print the result, so nothing about it is special beyond its convenience.

Generating keys from the Rails console

You can also use the rails console to produce one. Run SecureRandom.hex(64) in the console and copy the output. Never paste a value you generated into a chat, an issue or a ticket, and never reuse the value from a tutorial. Generate a separate key for each environment.

Where Rails reads the secret key base in each environment

Generating the value is the easy half. The harder half is knowing where Rails looks for it, because several places can supply it and the first match wins. Understanding the lookup order explains most of the confusing "missing secret_key_base" errors you will meet when you deploy.

Development and test environment behavior

In development and test, you do not need to configure anything. Rails 7.1 and later create a file named tmp/local_secret.txt and read the value from it; before 7.1 the file was tmp/development_secret.txt. The file lives in tmp, so it is ignored by git and each developer gets a different key.

Production, staging and other deployed environments

Every other environment, including production and staging, follows a fixed precedence. Rails checks the SECRET_KEY_BASE environment variable first, then credentials.secret_key_base, and finally the legacy secrets file.

Precompiling assets without a real secret

Building a Docker image usually runs asset compilation, and that step boots the application, which wants a key. You do not have to bake a real key into the image. Set SECRET_KEY_BASE_DUMMY=1 for that one command and Rails substitutes a random placeholder, so the real value only appears at runtime on the server.

Rails secrets vs Rails credentials: where to store the key

Rails has stored this value in three different ways over the years, and old blog posts still describe all of them. Knowing which one your version expects saves hours.

• Rails 4.1 introduced plain config/secrets.yml, a yaml file holding secrets for every environment.
• Rails 5.1 added encrypted secrets with a separate key file, and Rails 5.2 replaced them with credentials.
• Rails 6.0 added multi-environment credentials, with one encrypted file and one key per environment.
• Rails 7.1 deprecated the secrets API and moved the secret_key_base lookup toward credentials.

Rails credentials and the master key

Rails credentials are the supported mechanism today. A new project made with rails new generates config/credentials.yml.enc, an encrypted file you can commit, plus config/master.key, the encryption key that decrypts it. Keep master.key out of your source code repository; the generated .gitignore already excludes it. On a server you can supply the same key through the RAILS_MASTER_KEY environment variable instead of a file.

bin/rails credentials:edit
# secret_key_base: <paste the generated value>

Credentials hold more than this one value: API keys, usernames and other sensitive configuration can sit in the same encrypted file. Per-environment files such as config/credentials/production.yml.enc keep production data away from developers who only need the development key.

The deprecated secrets file and the deprecation warning

If you maintain an older app, you may see a deprecation warning telling you that Rails.application.secrets is deprecated in favor of credentials. It appears even when you never wrote a secrets file yourself, because some library code still reads it. The file config/secrets.yml is kept only for backwards compatibility and is not where new work should go. Rails secrets still work in the current release, but the Rails 7.1 release notes and the Rails 5.2 release notes both point you toward credentials, so new code should not depend on Rails secrets at all.

Using an environment variable instead

Many teams skip both files and store the value as an environment variable on the platform that runs the application, such as Heroku config vars or a container orchestrator. That works well because the key never touches the repository. It only needs SECRET_KEY_BASE set to your generated string before the server boots.

• Set the variable in your hosting dashboard, not in a committed file.
• Use a different value for each deployed environment.
• Add the same variable to continuous integration only if tests need production-like cookies.
• Read the final value in code through Rails.application.secret_key_base, never from a source-specific attribute.

Rails secrets and credentials in practice: files, commands and access

The history above explains why two systems exist; this section shows how each one behaves day to day. Both store sensitive configuration for your application, and both can carry the secret_key_base, but they differ in encryption, file layout and the commands you use to edit them.

Encrypted secrets and the config/secrets.yml.enc file

Encrypted secrets arrived in Rails 5.1 as a way to commit secrets safely. The values live in config/secrets.yml.enc, and a companion key file named config/secrets.yml.key unlocks them. Rails will merge the encrypted secrets with the plain text config/secrets.yml during initialization, so an older application can run both side by side. The command that created the encrypted file, bin/rails secrets:setup, was removed once credentials arrived, and it now tells you to use credentials instead.

• The plain text secrets file should never be committed with real production values.
• Encrypted secrets can be committed because they need the key file or RAILS_MASTER_KEY to decrypt.
• Both kinds of secrets are read through Rails.application.secrets, which is now deprecated.
• Credentials replace the encrypted secrets configuration entirely and need no extra setting to activate.

Rails credentials files and multi-environment credentials

Credentials are always encrypted and need no opt-in flag. The default credentials file, config/credentials.yml.enc, is shared by every environment and decrypted with config/master.key. With multi-environment credentials, Rails prefers an environment-specific file such as config/credentials/production.yml.enc and its own key, falling back to the shared file when none exists. That lets a production encryption key live only on the production server while developers work with the development file.

• Run bin/rails credentials:edit to open the shared encrypted credentials in your editor.
• Add --environment production to edit a single environment's credentials file instead.
• The editor needs the master key, from the key file or the RAILS_MASTER_KEY environment variable.
• If the key is lost, the encrypted file cannot be decrypted, and you must create new credentials from scratch.
• Embedded Ruby is not supported inside the encrypted yaml, so every value must be written literally.

Because credentials are plain yaml once decrypted, the configuration is easy to read and diff in your editor, but the file on disk stays opaque. Treat the decrypted contents with the same care as any secret: do not paste them into logs, issues or screenshots.

Which secret_key_base accessor should your application call

One reason this topic confuses people is that Rails exposes the value in several places at once. Each accessor reads a different source, and only one of them applies the full precedence rules.

• Rails.application.secret_key_base returns the value for the current environment after checking every source; call this one.
• Rails.application.credentials.secret_key_base reads only the encrypted credentials file.
• Rails.application.secrets.secret_key_base reads only the deprecated secrets files and prints a deprecation warning.
• Rails.application.config.secret_key_base is the configuration setting, which Rails fills in during initialization.
• The SECRET_KEY_BASE environment variable overrides the others in every environment except development and test.

Application code should almost never need the raw string. If you find yourself passing it around, ask whether a message verifier, a message encryptor or the key generator on the application object can do the job instead, because those ActiveSupport classes derive purpose-specific keys and keep the root secret_key_base out of your own code. Both ActiveSupport::MessageVerifier and ActiveSupport::MessageEncryptor accept a derived key rather than the raw string.

Why a Rails secret key base also matters for encryption and signing

Developers sometimes assume the value is only used for logins, but it is the root of encryption and signing across the whole framework. Each purpose gets its own derived key, produced from the secret_key_base plus a salt string, so the key that signs a cookie differs from the one that encrypts a session.

• Signing proves a message came from your application and was not altered.
• Encryption hides the contents so a visitor cannot decrypt a cookie in the browser.
• Signed and encrypted values can be verified or decrypted only by an application holding the same secret_key_base.
• Every Rails engine and library that uses an ActiveSupport message verifier inherits the same root secret_key_base.

This is also why consistency matters across servers. If two instances of one application run with different values, a cookie signed by the first will fail verification on the second, and users will be logged out at random as the load balancer moves them. Give every instance of an application the same value, and give each environment its own.

Development and test configuration for a local application

In development the secret_key_base comes from tmp/local_secret.txt, generated on first boot and reused afterwards. Delete the file and the next boot creates a new value, which signs out your local sessions, so it is a handy way to test how your application reacts to a rotated secret_key_base before you do it in production.

Docker, continuous integration and precompile assets

Container builds and pipelines run your application without a real server, so they should not receive production secrets. For a Docker image, set SECRET_KEY_BASE_DUMMY=1 only on the command that runs assets:precompile, so the build can boot Rails to precompile assets and the placeholder is discarded. For continuous integration, rely on the generated development and test key unless a test explicitly needs signed cookies from a known value, in which case set a throwaway environment variable for that job.

Generate a Rails secret key and add it to your app: step by step

Here is the whole workflow on one page, from empty configuration to a running deployment.

1. Run bin/rails secret to generate a fresh random string for the environment you are configuring.
2. Decide where the value lives: the SECRET_KEY_BASE environment variable, or encrypted credentials edited with bin/rails credentials:edit.
3. Store it on the server or in your secrets manager; do not paste it into a committed file.
4. Restart the application so the initializer reads the new value.
5. Open the Rails console and run Rails.application.secret_key_base to confirm the application sees it.

Checking which source Rails is using

The most reliable check is the method Rails itself calls. Rails.application.secret_key_base returns the value for the current environment after applying the precedence above, so it tells you what the server really uses rather than what you hoped it uses. Compare the first few characters to the one you generated, and never print the whole value into shared logs.

Fixing the missing secret_key_base error in production

When the server fails with a message that secret_key_base is missing for the production environment, none of the three sources produced a value. Usually the environment variable was set on the wrong app, the credentials file was decrypted with the wrong master key, or the process was not restarted after the change. Work through those three in order before generating anything new.

Keeping your Rails secret key base safe, and rotating it

Treat the secret_key_base like a database password: rotate it on a schedule and immediately after any leak. Rotation is routine maintenance and a leak is an emergency, but the procedure is the same: generate a new value, deploy it, and retire the old one.

What to do when the key is compromised

If the value reached a public repository, treat it as known to attackers. Generate a new one, deploy it, and remove the old one from history if you can. Be aware of the consequence: changing the value invalidates existing sessions and anything signed with it, so every user is signed out and encrypted cookies stop decrypting. Plan the change for a quiet period and announce it where it matters.

Security scanners search public code for exposed Rails keys, which is why leaked ones get abused quickly. Rotating promptly matters more than rewriting git history, because anyone who cloned the repository in the meantime still has the old value.

Habits that protect every environment

• Never commit config/master.key, tmp/local_secret.txt or a plain text secrets file.
• Use a different secret_key_base in development, staging and production.
• Limit who can read production credentials, and share the master key through a password manager.
• Rotate after an employee with access leaves, and after any suspected exposure.
• Keep the Rails version current so you inherit stronger defaults on every upgrade.

Moving from secrets to credentials during an upgrade

An upgrade from Rails 7.0 to 7.1 is the point where many teams first notice the secrets deprecation. A safe migration copies each environment's values into credentials, updates any code reading Rails.application.secrets, and then deploys with the master key available on every server and in continuous integration. Read the release notes for your target version before you change anything, and migrate one environment at a time so that a mistake in staging never reaches production.

Frequently Asked Questions

How is this different from rails secret?

It produces an identical format -- 64 random bytes encoded as 128 lowercase hex characters -- computed in your browser instead of via the Rails command line. Use this when you need a value quickly without a local Rails installation or terminal access.

Where should I put the generated value?

As of Rails 5.2+, store it via encrypted credentials (bin/rails credentials:edit, under secret_key_base:) rather than a plain environment variable or config/secrets.yml -- the credentials system is the current recommended approach and keeps the value encrypted at rest in your repository.

What does secret_key_base actually protect?

It's the root key Rails uses to derive signing and encryption keys for session cookies, CSRF tokens, and any data processed through ActiveSupport::MessageEncryptor or MessageVerifier. Anyone who obtains it can forge signed cookies or decrypt encrypted session data for your application.

What happens if I change secret_key_base?

Every existing session and any previously signed or encrypted cookie value becomes invalid immediately -- all logged-in users will be signed out. Treat rotation the same way you'd treat any other credential rotation: deliberate, and expected to force re-authentication.

Is secret_key_base the same as the Rails master key?

No -- the master key (config/master.key) is used once at boot to decrypt your encrypted credentials file, which is where secret_key_base itself is typically stored. They're related but distinct: rotating the master key alone doesn't invalidate sessions, but rotating secret_key_base always does.