RubyGems.org 2FA: how to set up an authenticator app

Your RubyGems.org account is the one behind gem push, gem yank and gem ownership, so anyone who takes it over can ship code to everyone who installs your gems. RubyGems.org calls two-factor authentication multi-factor authentication (MFA). It's optional for most people, but required if you own a gem with more than 180 million total downloads (RubyGems.org). Gem owners can also make it a condition for publishing a particular gem, which then applies to every owner of that gem (RubyGems.org).

You can use a security device or passkey (WebAuthn, which RubyGems.org recommends) or an authenticator app with one-time codes. There are no text-message codes: "SMS-based authentication or recovery is not supported" (RubyGems.org). This guide covers the authenticator app, using Authenticator App - Novaz on iPhone. Any authenticator app works the same way.

How we checked this guide: the RubyGems.org steps come from the official RubyGems Guides and the RubyGems blog, linked below, which we read on October 21, 2026. We haven't tested them on a RubyGems.org account, so a label may differ slightly. The Novaz steps are checked against the app, version 1.0.5.

Turn on MFA with an authenticator app

RubyGems.org's guide describes these steps (RubyGems.org):

1. Sign in on the website and open the edit settings page.
2. Find the Multi-factor Authentication section. It has two options, Authentication App and Security Device.
3. Choose register a new device under the authenticator option. A page opens with a QR code and a box for a code.
4. In Novaz, tap +, then Scan QR code, and point the camera at the code. If the page is open on the same iPhone, take a screenshot, tap +, then Choose a photo. See scanning a QR code on the same iPhone.
5. If you'd rather type it, the page shows an Account and a Key next to the QR code. In Novaz, tap +, then Enter key manually, and paste the key into Setup key. See What is a 2FA setup key?
6. Type the 6-digit code from Novaz into OTP Code and click Enable.
7. RubyGems.org shows your recovery codes. Save them before you leave the page.
8. Sign out and sign back in. The sign-in should now ask for a code.

Don't leave the page open too long: the guide says the QR code can expire. If your code is refused, start the setup again. The codes are 6 digits and change every 30 seconds, the same as Novaz makes from a typed key, so scanning and typing both work.

Choose what needs a code

Turning on MFA sets the level to UI and API (Recommended). The settings page lets you pick one of two levels from a dropdown, then click Update and confirm with a code (RubyGems.org):

• UI and API (Recommended): codes for website actions and for gem signin, gem push, gem owner --add and gem owner --remove.
• UI and gem signin: codes for the website and gem signin only. At this level you can still require MFA on individual API keys.

Gems with more than 180 million downloads need one of these two levels before their owners can push, yank or manage owners (RubyGems.org).

Codes on the command line

With an authenticator app, the gem command prompts for a code when it needs one. You can also pass it up front with the --otp option, as in gem signin --otp 123456. RubyGems.org checks the code each time you run one of those commands, not just when you sign in. The UI and API level needs the gem command that ships with Ruby 2.6 or later, or RubyGems 3.0 or later (RubyGems.org).

Your recovery codes

RubyGems.org shows the recovery codes once, when you turn MFA on. Each works one time. To use one, type it where the site asks for your code (RubyGems.org). The guide doesn't say whether you can make a new set later, so treat the first set as the only one.

Keep these codes even if you back up Novaz: they get you in if the phone is gone and your Novaz backup is missing or out of date. Keep them in a password manager or on paper, away from the phone. See 2FA backup codes.

Moving to a new iPhone

This is where RubyGems.org differs from many services. To set up the authenticator again, you have to remove the current one with a recovery code, then register the new phone. The guide warns that re-setup on a new device can take up to two recovery codes (RubyGems.org). Plan for that before you switch, and count how many codes you have left.

With Novaz you can avoid this: restore your accounts on the new iPhone from iCloud backup or a backup file, and the same codes keep working, so no recovery codes get used. Without a Novaz backup, the new phone needs this setup. See How to transfer your authenticator app to a new iPhone. A security key registered alongside the app gives you a second way in. The guide describes adding one in the Security Device section and doesn't mention a recovery code for it.

If RubyGems.org rejects your code

The guides don't cover rejected codes. Check that your iPhone sets its clock on its own: Settings > General > Date & Time > Set Automatically. Novaz warns you when the clock is 15 seconds or more off. During setup, a rejected code can also mean the QR code expired. More causes are in Authenticator code not working?

If you lose your authenticator

Sign in with an unused recovery code in place of the code, then remove the old authenticator and set up a new one. A registered security device also works.

If you have neither, the guides don't describe a recovery process. The Help link at the bottom of rubygems.org goes to support@rubygems.org, and the blog post on required MFA sends people needing account help to that address (RubyGems.org). RubyGems.org doesn't say what proof it asks for or how long it takes. See Lost the phone with your authenticator app?

Official RubyGems.org help

• Setting up multi-factor authentication
• Using multi-factor authentication in command line
• Requiring MFA on popular gem maintainers