docs: update documentation for granular access token bypass 2FA feature
- Add bypass 2FA option to granular access tokens documentation - Update token creation instructions to include 2FA bypass configuration - Clarify that GATs can bypass 2FA for CI/CD workflows - Update 2FA requirement documentation for package publishing - Add notes about GAT bypass capability in CI/CD workflow guides - Update CLI documentation to mention GATs alongside automation tokens This update documents the new capability for granular access tokens to bypass two-factor authentication requirements, making them suitable for automated CI/CD workflows while maintaining security flexibility.
Karthikeyan Padaikathu committed
Oct 27, 2025 at 14:00 UTC
6b04817a6294e80e13bd8e922302206246c46b9a
7 files changed
+23
-9
content/cli/v10/commands/npm-token.mdx
+1
-1
@@ -47,7 +47,7 @@ Publish token npm_… with id e0cf92 created 2017-10-02
47
48
- `npm token create [--read-only] [--cidr=<cidr-ranges>]`: Create a new authentication token. It can be `--read-only`, or accept a list of [CIDR](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing) ranges with which to limit use of this token. This will prompt you for your password, and, if you have two-factor authentication enabled, an otp.
49
50
- Currently, the cli can not generate automation tokens. Please refer to the [docs website](https://docs.npmjs.com/creating-and-viewing-access-tokens) for more information on generating automation tokens.
50
+ Currently, the cli can not generate automation tokens or granular access tokens. Please refer to the [docs website](https://docs.npmjs.com/creating-and-viewing-access-tokens) for more information on generating automation tokens and granular access tokens.
51
52
```
53
Created publish token a73c9572-f1b9-8983-983d-ba3ac3cc913d
content/cli/v11/commands/npm-token.mdx
+1
-1
@@ -63,7 +63,7 @@ Publish token npm_… with id e0cf92 created 2017-10-02
63
64
- `npm token create [--read-only] [--cidr=<cidr-ranges>]`: Create a new authentication token. It can be `--read-only`, or accept a list of [CIDR](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing) ranges with which to limit use of this token. This will prompt you for your password, and, if you have two-factor authentication enabled, an otp.
65
66
- Currently, the cli can not generate automation tokens. Please refer to the [docs website](https://docs.npmjs.com/creating-and-viewing-access-tokens) for more information on generating automation tokens.
66
+ Currently, the cli can not generate automation tokens or granular access tokens. Please refer to the [docs website](https://docs.npmjs.com/creating-and-viewing-access-tokens) for more information on generating automation tokens and granular access tokens.
67
68
```
69
Created publish token a73c9572-f1b9-8983-983d-ba3ac3cc913d
content/getting-started/setting-up-your-npm-user-account/about-two-factor-authentication.mdx
+7
@@ -44,6 +44,12 @@ By default, 2FA is enabled for authorization and writes. We will request a secon
44
| Change user and team package access | [`npm access grant/revoke`][access] |
45
| [Change package 2FA requirements][pkg-2fa] | [`npm access 2fa-required/2fa-not-required`][access] |
46
47
+<Note>
48
+
49
+**Note:** [Granular access tokens][granular-tokens] can be configured to bypass 2FA requirements, making them ideal for CI/CD workflows and automation scenarios. When a granular access token is set to bypass 2FA, operations performed with that token will not require additional authentication factors.
50
+
51
+</Note>
52
+
53
### Authorization only
54
55
If you enable 2FA for authorization only. We will request a second form of authentication only for certain authorized actions.
@@ -68,6 +74,7 @@ If you enable 2FA for authorization only. We will request a second form of authe
74
[deprecate]: https://docs.npmjs.com/cli/deprecate
75
[access]: https://docs.npmjs.com/cli/access
76
[pkg-2fa]: /requiring-2fa-for-package-publishing-and-settings-modification
77
+[granular-tokens]: /integrations/integrating-npm-with-external-services/about-access-tokens#about-granular-access-tokens
78
[authy]: https://authy.com/download/
79
[google-authenticator]: https://support.google.com/accounts/answer/1066447
80
[microsoft-authenticator]: https://www.microsoft.com/security/mobile-authenticator-app
content/integrations/integrating-npm-with-external-services/about-access-tokens.mdx
+4
-1
@@ -52,8 +52,11 @@ Granular access tokens allow you to restrict access provided to the token based
52
- Set a token expiration date
53
- Limit token access based on IP address ranges
54
- Select between **read-only** or **read and write** access
55
+- Configure whether the token can bypass two-factor authentication (2FA) requirements
56
56
-You can create up to 1000 granular access tokens on your npm account. You can set how long your token is valid for, at least one day in the future. Each token can access up to 50 organizations, and up to either 50 packages, 50 scopes, or a combination of 50 packages and scopes. Access tokens are tied to users’ permission; hence it cannot have more permission than the user at any point in time. If a user has their access revoked from a package or an org., their granular access token also will have its access revoked from those packages or org.
57
+You can create up to 1000 granular access tokens on your npm account. You can set how long your token is valid for, at least one day in the future. Each token can access up to 50 organizations, and up to either 50 packages, 50 scopes, or a combination of 50 packages and scopes. Access tokens are tied to users' permission; hence it cannot have more permission than the user at any point in time. If a user has their access revoked from a package or an org., their granular access token also will have its access revoked from those packages or org.
58
+
59
+Granular access tokens can be configured to bypass 2FA requirements, making them ideal for CI/CD workflows and automation scenarios where interactive 2FA prompts are not feasible. When a granular access token is set to bypass 2FA, it will not require additional authentication factors when performing operations on npm, similar to automation tokens.
60
61
When you give a token access to an organization, the token can only be used for managing organization settings and teams or users associated with the organization. It does not give the token the right to publish packages managed by the organization.
62
content/integrations/integrating-npm-with-external-services/creating-and-viewing-access-tokens.mdx
+6
-2
@@ -75,11 +75,15 @@ You can [create](#creating-access-tokens) and [view](#viewing-access-tokens) acc
75
76
_**Note**: When you give a token access to an organization, the token can only be used for managing organization settings and teams or users associated with the organization. It does not give the token the right to publish packages managed by the organization._
77
78
-9. Review the token summary, then click **Generate Token**.
78
+9. (Optional) In the **Two-Factor Authentication** section, configure whether the token can bypass 2FA requirements.
79
+ - Check **Bypass two-factor authentication** to allow the token to bypass 2FA requirements when performing operations on npm. This is ideal for CI/CD workflows and automation scenarios.
80
+ - Leave unchecked if you want the token to require 2FA for sensitive operations.
81
+
82
+10. Review the token summary, then click **Generate Token**.
83
84
<Screenshot src="/integrations/integrating-npm-with-external-services/granular-access-token-summary.png" alt="Screenshot of the granular access token summary and the generate token button" />
85
82
-10. Copy the token from the top of page.
86
+11. Copy the token from the top of page.
87
88
### Creating tokens with the CLI
89
content/integrations/integrating-npm-with-external-services/using-private-packages-in-a-ci-cd-workflow.mdx
+1
-1
@@ -24,7 +24,7 @@ For more information on creating access tokens, including CIDR-whitelisted token
24
25
### Continuous deployment
26
27
-Since continuous deployment environments usually involve the creation of a deploy artifact, you may wish to create an [automation token][create-token] on the website. This will allow you to publish even if you have two-factor authentication enabled on your account.
27
+Since continuous deployment environments usually involve the creation of a deploy artifact, you may wish to create an [automation token][create-token] or a [granular access token][create-token] configured to bypass 2FA on the website. This will allow you to publish even if you have two-factor authentication enabled on your account.
28
29
### Interactive workflows
30
content/packages-and-modules/securing-your-code/requiring-2fa-for-package-publishing-and-settings-modification.mdx
+3
-3
@@ -6,7 +6,7 @@ import shared from '~/shared.js'
6
7
To protect your packages, as a package publisher, you can require everyone who has write access to a package to have two-factor authentication (2FA) enabled. This will require that users provide 2FA credentials in addition to their login token when they publish the package. For more information, see "[Configuring two-factor authentication][config-2fa]".
8
9
-You may also choose to allow publishing with either two-factor authentication _or_ with [automation tokens][creating-automation-token]. This lets you configure automation tokens in a CI/CD workflow, but requires two-factor authentication from interactive publishes.
9
+You may also choose to allow publishing with either two-factor authentication _or_ with [automation tokens][creating-automation-token] or [granular access tokens][creating-granular-access-token] configured to bypass 2FA. This lets you configure tokens in a CI/CD workflow, but requires two-factor authentication from interactive publishes.
10
11
## Configuring two-factor authentication
12
@@ -25,10 +25,10 @@ You may also choose to allow publishing with either two-factor authentication _o
25
With this option, a maintainer can publish a package or change the package settings whether they have two-factor authentication enabled or not. This is the least secure setting.
26
27
2. **Require two-factor authentication or automation tokens or granular access token**
28
- With this option, maintainers must have two-factor authentication enabled for their account. If they publish a package interactively, using the `npm publish` command, they will be required to enter 2FA credentials when they perform the publish. However, maintainers may also create an [automation token][creating-automation-token] or a [granular access token][creating-granular-access-token] and use that to publish. A second factor is _not_ required when using a token, making it useful for continuous integration and continuous deployment workflows.
28
+ With this option, maintainers must have two-factor authentication enabled for their account. If they publish a package interactively, using the `npm publish` command, they will be required to enter 2FA credentials when they perform the publish. However, maintainers may also create an [automation token][creating-automation-token] or a [granular access token][creating-granular-access-token] configured to bypass 2FA and use that to publish. A second factor is _not_ required when using a token configured to bypass 2FA, making it useful for continuous integration and continuous deployment workflows.
29
30
3. **Require two-factor authentication and disallow tokens**
31
- With this option, a maintainer must have two-factor authentication enabled for their account, and they must publish interactively. Maintainers will be required to enter 2FA credentials when they perform the publish. Automation tokens and granular access tokens cannot be used to publish packages.
31
+ With this option, a maintainer must have two-factor authentication enabled for their account, and they must publish interactively. Maintainers will be required to enter 2FA credentials when they perform the publish. Automation tokens and granular access tokens configured to bypass 2FA cannot be used to publish packages.
32
33
<Screenshot src="/packages-and-modules/securing-your-code/2fa-package-setting.png" alt="Screenshot showing the require two-factor option for a package" />
34