adding new TOTP disabled docs (#1746)
changes from https://github.com/npm/documentation/pull/1740 ## References <!-- Examples: Related to #0 Depends on #0 Blocked by #0 Fixes #0 Closes #0 -->
sam crochet committed
Oct 13, 2025 at 12:54 UTC
53f50b0ffdefe2496854f2ef1f368de500699754
5 files changed
+13
-86
content/getting-started/setting-up-your-npm-user-account/about-two-factor-authentication.mdx
+1
-5
@@ -10,10 +10,9 @@ redirect_from:
10
- Something you have (e.g., an ID badge or a cryptographic key).
11
- Something you are (e.g., a fingerprint or other biometric data).
12
13
-When you enable 2FA, you will be prompted for a second form of authentication before performing certain actions on your account or packages to which you have write access. Depending on your 2FA configuration you will be either prompted to authenticate with a [security-key][webauthn] or a [time-based one-time password (TOTP)][totp].
13
+When you enable 2FA, you will be prompted for a second form of authentication before performing certain actions on your account or packages to which you have write access. You will be prompted to authenticate with a [security-key][webauthn].
14
15
- The security-key flow allows you to use biometric devices such as Apple [Touch ID][touch-id], [Face ID][face-id] or [Windows Hello][windows-hello] as well as physical keys such as [Yubikey][yubikey], [Thetis][thetis] or [Feitian][feitian] as your 2FA.
16
-- To configure TOTP you will need to install an authenticator application that can generate OTPs such as [Authy][authy], [Google Authenticator][google-authenticator], or [Microsoft Authenticator][microsoft-authenticator] on your mobile device.
16
17
<Note>
18
@@ -68,9 +67,6 @@ If you enable 2FA for authorization only. We will request a second form of authe
67
[deprecate]: https://docs.npmjs.com/cli/deprecate
68
[access]: https://docs.npmjs.com/cli/access
69
[pkg-2fa]: /requiring-2fa-for-package-publishing-and-settings-modification
71
-[authy]: https://authy.com/download/
72
-[google-authenticator]: https://support.google.com/accounts/answer/1066447
73
-[microsoft-authenticator]: https://www.microsoft.com/security/mobile-authenticator-app
70
[webauthn]: https://webauthn.guide/
71
[can-i-use]: https://caniuse.com/#search=webauthn
72
[u2f]: https://en.wikipedia.org/wiki/Universal_2nd_Factor
content/getting-started/setting-up-your-npm-user-account/configuring-two-factor-authentication.mdx
+12
-46
@@ -4,7 +4,7 @@ title: Configuring two-factor authentication
4
5
import shared from '~/shared.js'
6
7
-You can enable two-factor authentication (2FA) on your npm user account to protect against unauthorized access to your account and packages, either by using a [security-key][webauthn] or [time-based one-time password (TOTP)][totp] from a mobile app.
7
+You can enable two-factor authentication (2FA) on your npm user account to protect against unauthorized access to your account and packages using a [security-key][webauthn].
8
9
## Prerequisites
10
@@ -12,16 +12,9 @@ Before you enable 2FA on your npm user account, you must:
12
13
- Update your npm client to version 5.5.1 or higher.
14
- To configure a security-key requires a modern browser that support [WebAuthn][can-i-use]. This will allow you to configure a biometric devices featuring Apple [Touch ID][touch-id], [Face ID][face-id], or [Windows Hello][windows-hello] as well as physical keys such as [Yubikey][yubikey], [Thetis][thetis], or [Feitian][feitian].
15
-- To configure TOTP you will need to install an authenticator application that can generate OTPs such as [Authy][authy], [Google Authenticator][google-authenticator], or [Microsoft Authenticator][microsoft-authenticator] on your mobile device.
15
16
For more information on supported 2FA methods, see "[About two-factor authentication][about-two-factor-authentication]".
17
19
-<Note>
20
-
21
-**Note:** npm does not accept SMS (text-to-phone) as a 2FA method.
22
-
23
-</Note>
24
-
18
## Configuring 2FA from the website
19
20
### Enabling 2FA
@@ -44,8 +37,8 @@ For more information on supported 2FA methods, see "[About two-factor authentica
37
38
<Screenshot src="/getting-started/setting-up-your-npm-user-account/device-selection.png" alt="Screenshot showing 2FA types" />
39
47
-6. Configure the 2FA method of your choice:
48
- - When using a **security-key**, provide a name for it and click **Add security key**. Follow the browser specific steps to add your security-key.
40
+6. Configure your security-key:
41
+ - Provide a name for your security-key and click **Add security key**. Follow the browser specific steps to add your security-key.
42
43
<Screenshot src="/getting-started/setting-up-your-npm-user-account/2fa-add-security-key.png" alt="Screenshot showing security key setup" />
44
@@ -53,10 +46,6 @@ For more information on supported 2FA methods, see "[About two-factor authentica
46
47
<Screenshot src="/getting-started/setting-up-your-npm-user-account/touch-id-mac-edge.png" alt="Screenshot showing 2FA device selection" />
48
56
-- When using an **authenticator application** on your phone, open it and scan the QR code on the two-step verification page. Enter the code generated by the app, then click **Verify**.
57
-
58
- <Screenshot src="/getting-started/setting-up-your-npm-user-account/2fa-verify.png" alt="Screenshot showing 2FA device selection" />
59
-
49
7. On the recovery code page, copy the recovery codes to your computer or other safe location that is not your second factor device. We recommend using a password manager.
50
51
<Screenshot src="/getting-started/setting-up-your-npm-user-account/recovery-code.png" alt="Screenshot showing the Recovery Code page" />
@@ -123,9 +112,9 @@ If you have 2FA enabled, you can remove it from your account settings page.
112
113
## Configuring 2FA from the command line
114
126
-### Enabling 2FA from the command line
115
+### Enabling 2FA settings from the command line
116
128
-Although security-key with WebAuthn can be used for authentication from both the web and the command line, it can only be configured from the web. When enabling 2FA from the command line, currently the only available option is to use an TOTP mobile app.
117
+Security-key with WebAuthn can be used for authentication from both the web and the command line, but it can only be configured from the web. We recommend configuring 2FA using security-keys through the web interface.
118
119
<Note>
120
@@ -133,6 +122,10 @@ Although security-key with WebAuthn can be used for authentication from both the
122
123
</Note>
124
125
+For the best security experience, we recommend configuring 2FA through the web interface where you can set up security-key authentication.
126
+
127
+If you need to enable 2FA from the command line:
128
+
129
1. If you are logged out on the command line, log in using `npm login` command.
130
131
2. On the command line, type the [`npm profile`](/cli/profile) command along with the option for the 2FA mode you want to enable:
@@ -148,24 +141,9 @@ Although security-key with WebAuthn can be used for authentication from both the
141
npm profile enable-2fa auth-only
142
```
143
151
-3. To add npm to your authenticator application, using the device with the app, you can either:
152
- - Scan the QR code displayed on the command line.
153
- - Type the number displayed below the QR code.
154
-
155
-4. When prompted to add an OTP code from your authenticator, on the command line, enter a one-time password generated by your authenticator app.
156
-
157
-### Sending a one-time password from the command line
158
-
159
-If you have enabled 2FA auth-and-writes, you will need to send the TOTP from the command line for certain commands to work. To do this, append `--otp=123456` (where _123456_ is the code generated by your authenticator) at the end of the command. Here are a few examples:
144
+### Using 2FA with commands
145
161
-```
162
-npm publish [<tarball>|<folder>][--tag <tag>] --otp=123456
163
-npm owner add <user > --otp=123456
164
-npm owner rm <user> --otp=123456
165
-npm dist-tags add <pkg>@<version> [<tag>] --otp=123456
166
-npm access edit [<package>) --otp=123456
167
-npm unpublish [<@scope>/]<pkg>[@<version>] --otp=123456
168
-```
146
+If you have enabled 2FA auth-and-writes, authentication will be handled automatically when using security-keys. For commands that require 2FA, you will be prompted to authenticate with your configured 2FA method.
147
148
### Removing 2FA from the command line
149
@@ -181,9 +159,7 @@ npm unpublish [<@scope>/]<pkg>[@<version>] --otp=123456
159
160
<Prompt>npm password:</Prompt>
161
184
-4. When prompted for a one-time password, enter a password from your authenticator app:
185
-
186
- <Prompt>Enter one-time password from your authenticator: <strong>123456</strong></Prompt>
162
+4. You will be prompted to authenticate with your configured 2FA method to complete the removal.
163
164
## Configuring account recovery options
165
@@ -210,22 +186,12 @@ When you enable 2FA on your npm user account, we strongly recommend you link you
186
187
The Twitter or GitHub account is now linked to your npm account. To remove the link to either account, you can click the **Remove** button next to the account you want to remove from your npm account.
188
213
-## Resolving TOTP errors
214
-
215
-If you are entering what seems to be a valid [TOTP][totp] but you see an error, be sure that you are using the correct authenticator account. If you have multiple authenticator accounts, using an TOTP from the wrong account will cause an error.
216
-
217
-Also, when you reset two-factor authentication after it has been disabled, the authenticator might create a second account with the same name. Please see the authenticator documentation to delete the old account.
218
-
189
[about-two-factor-authentication]: /about-two-factor-authentication
190
[authorization-and-writes]: /about-two-factor-authentication#authorization-and-writes
191
[login]: /cli/adduser
192
[recovering-your-2fa-enabled-account]: /recovering-your-2fa-enabled-account
193
[can-i-use]: https://caniuse.com/#search=webauthn
194
[viewing-and-regenerating-recovery-code]: /recovering-your-2fa-enabled-account#viewing-and-regenerating-recovery-code
225
-[totp]: https://en.wikipedia.org/wiki/Time-based_one-time_password
226
-[authy]: https://authy.com/download/
227
-[google-authenticator]: https://support.google.com/accounts/answer/1066447
228
-[microsoft-authenticator]: https://www.microsoft.com/security/mobile-authenticator-app
195
[webauthn]: https://webauthn.guide/
196
[u2f]: https://en.wikipedia.org/wiki/Universal_2nd_Factor
197
[windows-hello]: https://support.microsoft.com/en-us/windows/learn-about-windows-hello-and-set-it-up-dae28983-8242-bb2a-d3d1-87c9d265a5f0
content/getting-started/setting-up-your-npm-user-account/recovering-your-2fa-enabled-account.mdx
-35
@@ -22,8 +22,6 @@ If you have misplaced the device that provided second-factor authentication, you
22
23
<>{shared['use-recovery-code'].image}</>
24
25
- _Note: If you have configured to use TOTP, you will see an TOTP prompt instead_
26
-
25
4. Enter an unused recovery code in the "Use a Recovery Code" prompt.
26
27
<Screenshot src="/getting-started/setting-up-your-npm-user-account/user-a-recovery-code.png" alt="Screenshot showing use a recovery code prompt with an input box to enter the recovery code" />
@@ -32,38 +30,6 @@ If you have misplaced the device that provided second-factor authentication, you
30
31
6. (Optional) To disable 2FA, see "[Disabling 2FA][removing-2fa-on-the-web]".
32
35
-### Using recovery code from the command line
36
-
37
-1. Locate the recovery codes generated when you enabled 2FA on your account.
38
-
39
-2. If you are logged out on the command line, log in using `npm login` command with your username and npm password.
40
-
41
-3. Enter an unused recovery code when you see this prompt:
42
-
43
- <Prompt>Enter one-time password:</Prompt>
44
-
45
-4. Once you are logged in, use the below and enter your npm password if prompted.
46
-
47
- ```
48
- npm profile disable-2fa
49
- ```
50
-
51
-5. Enter another unused recovery code when you see this prompt:
52
-
53
- <Prompt>Enter one-time password:</Prompt>
54
-
55
-6. npm will confirm that two-factor authentication has been disabled.
56
-
57
-7. Follow the steps outlined in "[Configuring two-factor authentication][configuring-two-factor-authentication]" to re-enable 2FA and generate new recovery codes.
58
-
59
-<Note>
60
-
61
-**Note:** Using the recovery codes to re-enable 2FA may create a new authenticator account with the same npm account name.
62
-
63
-If you are using a [time-based one-time password (TOTP)][totp] mobile app and want to delete the old authenticator account, follow the steps for the authenticator.
64
-
65
-</Note>
66
-
33
## Viewing and regenerating recovery code
34
35
<Note>
@@ -126,4 +92,3 @@ If you have misplaced both your 2FA device and your recovery codes, you can cont
92
[removing-2fa-on-the-web]: /configuring-two-factor-authentication#disabling-2fa
93
[using-recovery-code-on-the-web]: /recovering-your-2fa-enabled-account#using-recovery-code-on-the-web
94
[viewing-and-regenerating-recovery-code]: #viewing-and-regenerating-recovery-code
129
-[totp]: https://en.wikipedia.org/wiki/Time-based_one-time_password
static/getting-started/setting-up-your-npm-user-account/2fa-modify.png
Binary files a/static/getting-started/setting-up-your-npm-user-account/2fa-modify.png and b/static/getting-started/setting-up-your-npm-user-account/2fa-modify.png differ
static/getting-started/setting-up-your-npm-user-account/device-selection.png
Binary files a/static/getting-started/setting-up-your-npm-user-account/device-selection.png and b/static/getting-started/setting-up-your-npm-user-account/device-selection.png differ