.env · security🔒 100% client-side — never leaves your browser

Rails Secret Key Generator: SECRET_KEY_BASE and RAILS_MASTER_KEY

Generate a Rails secret key in your browser: this Rails secret key generator creates a 128-character SECRET_KEY_BASE (the same format as bin/rails secret) and a 32-character RAILS_MASTER_KEY for a new encrypted credentials file.

By Aliniyaz Mamat · last reviewed

Be the first to rate
SECRET_KEY_BASE (128 hex chars)
Matches rails secret output — used to sign session cookies
Key
.env line
SECRET_KEY_BASE=
RAILS_MASTER_KEY (32 hex chars)
Used to decrypt credentials.yml.enc
Key
.env line
RAILS_MASTER_KEY=
CLI alternative
SECRET_KEY_BASE
rails secret
RAILS_MASTER_KEY
openssl rand -hex 16

Key takeaways

  • ✓SECRET_KEY_BASE: 64 random bytes as hex = 128 characters, exactly what bin/rails secret prints.
  • ✓RAILS_MASTER_KEY: 16 random bytes as hex = 32 characters, the size Rails uses for config/master.key (AES-128-GCM).
  • ✓A new master key cannot open an existing credentials.yml.enc. Use it only for a new credentials file, or copy your real config/master.key instead.
  • ✓Changing SECRET_KEY_BASE invalidates sessions, signed and encrypted cookies and signed IDs, unless you add a cookie rotation.

What it does

  • ▸128-character SECRET_KEY_BASE (bin/rails secret format)
  • ▸32-character RAILS_MASTER_KEY for encrypted credentials
  • ▸Ready-to-paste .env / environment variable lines
  • ▸Generated with crypto.getRandomValues
  • ▸Nothing is uploaded or stored

Privacy

Runs 100% in your browser. Your .env never touches our servers.

client-side only

When to use this tool

  • →Setting SECRET_KEY_BASE on Heroku, Render, Fly.io or Kamal without a Ruby shell at hand
  • →Docker builds that need a value during assets:precompile
  • →Starting fresh credentials for a new environment (config/credentials/staging.yml.enc)
  • →Rotating SECRET_KEY_BASE after it was committed or logged

Common mistakes

  • ⚠Generating a new RAILS_MASTER_KEY for an app that already has credentials.yml.enc: Rails then raises ActiveSupport::MessageEncryptor::InvalidMessage
  • ⚠Committing config/master.key. Rails adds it to .gitignore for a reason
  • ⚠Using the real key during assets:precompile in a Docker build: it ends up in a layer. Use SECRET_KEY_BASE_DUMMY=1 (Rails 7.1+) for that step
  • ⚠Rotating SECRET_KEY_BASE without a cookie rotation and logging out every user by surprise

SECRET_KEY_BASE vs RAILS_MASTER_KEY

SECRET_KEY_BASERAILS_MASTER_KEY
Purposeroot secret for signing and encrypting cookies, sessions, signed IDs, Active Storage URLsdecrypts config/credentials.yml.enc
Format128 hex characters (64 bytes)32 hex characters (16 bytes)
Where it livesENV["SECRET_KEY_BASE"] or inside the credentials fileconfig/master.key or ENV["RAILS_MASTER_KEY"]
If you replace itusers are logged out, signed links breakthe existing credentials file can't be read
Commandbin/rails secretcreated by bin/rails credentials:edit

In production, Rails reads SECRET_KEY_BASE from the environment first and falls back to secret_key_base in the credentials. Setting the environment variable is the simplest option on most hosts.

Setting the keys in production

# Heroku
heroku config:set SECRET_KEY_BASE=<128 hex chars>
heroku config:set RAILS_MASTER_KEY=$(cat config/master.key)

# Fly.io
fly secrets set SECRET_KEY_BASE=<128 hex chars>

# Kamal: .kamal/secrets + config/deploy.yml env.secret
RAILS_MASTER_KEY=$(cat config/master.key)

Copy the real config/master.key for RAILS_MASTER_KEY in existing apps. The generated master key above is for new credentials files only.

Docker: precompiling assets without the real key

# Rails 7.1+: a throwaway secret only for this step
RUN SECRET_KEY_BASE_DUMMY=1 ./bin/rails assets:precompile

Rotating SECRET_KEY_BASE without logging everyone out

Rails can read cookies signed with an old secret and rewrite them with the new one. Add a rotation for the transition period:

config/initializers/cookie_rotator.rb
# Rails 7+ defaults (SHA256 key derivation). Matches the Rails guide pattern.
Rails.application.config.after_initialize do
  old_secret = ENV["OLD_SECRET_KEY_BASE"]
  next if old_secret.blank?

  config = Rails.application.config.action_dispatch
  key_generator = ActiveSupport::KeyGenerator.new(
    old_secret, iterations: 1000, hash_digest_class: OpenSSL::Digest::SHA256
  )
  config.cookies_rotations.tap do |cookies|
    cookies.rotate :encrypted, key_generator.generate_key(
      config.authenticated_encrypted_cookie_salt, ActiveSupport::MessageEncryptor.key_len
    )
    cookies.rotate :signed, key_generator.generate_key(config.signed_cookie_salt)
  end
end

Remove OLD_SECRET_KEY_BASE once sessions created before the switch have expired. If the old secret leaked, skip the rotation so stolen cookies stop working immediately. For Ruby's environment loading in general, see the Rails .env generator.

Frequently asked questions

What is the difference between SECRET_KEY_BASE and RAILS_MASTER_KEY?

SECRET_KEY_BASE signs and encrypts cookies, sessions and other messages. RAILS_MASTER_KEY only decrypts the encrypted credentials file. They are independent values.

Is this the same as bin/rails secret?

Yes. bin/rails secret prints SecureRandom.hex(64), 128 hexadecimal characters. The generator produces the same format from crypto.getRandomValues.

Can I use a generated RAILS_MASTER_KEY for my existing app?

No. The master key must be the one that encrypted credentials.yml.enc. A new key only works if you create a new credentials file, for example after deleting the old one and running bin/rails credentials:edit.

What happens if I change SECRET_KEY_BASE?

Existing sessions and signed or encrypted cookies stop validating, so users are logged out, and signed IDs and Active Storage links created before become invalid. A cookie rotation (above) softens this for sessions.

Do I need SECRET_KEY_BASE in development?

No. Since Rails 7.1, development and test generate one in tmp/local_secret.txt. Only production needs a real value.

Related tools

Learn more

Compare

coming soon

Get notified when env syncing launches

We're building a tiny tool to keep .env files in sync across teammates and environments. Leave your email — no spam, just a single launch ping.

We use your address only for this launch email. You can ask us to delete it at any time. Privacy policy