@cryptotaxi247 / documentation / commits / bebae10

docs: document granular access token 2FA bypass feature

Update registry documentation to reflect that Granular Access Tokens can now be configured to bypass 2FA requirements, making them the recommended modern alternative to legacy automation tokens for CI/CD workflows. Changes: - Updated about-access-tokens.mdx to emphasize GATs as superior alternative to automation tokens with enhanced security features - Added bypass 2FA configuration step to creating-and-viewing-access-tokens.mdx - Updated CI/CD workflow documentation to recommend GATs with bypass 2FA - Clarified package publishing 2FA requirements for tokens configured to bypass 2FA - Added comprehensive note in about-two-factor-authentication.mdx explaining GAT bypass capability and its advantages Note: CLI files (content/cli/**) are not modified as they are sourced from npm/cli repository and will be updated in a future npm release.

Karthikeyan Padaikathu committed Oct 28, 2025 at 15:22 UTC bebae101356143fdad42ee6b685e10e0463def1b
5 files changed +28 -14
content/getting-started/setting-up-your-npm-user-account/about-two-factor-authentication.mdx
+7
@@ -43,6 +43,12 @@ By default, 2FA is enabled for authorization and writes. We will request a secon
43 | Change user and team package access | [`npm access grant/revoke`][access] |
44 | [Change package 2FA requirements][pkg-2fa] | [`npm access 2fa-required/2fa-not-required`][access] |
45
46 +<Note>
47 +
48 +**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. This provides the same automation benefits as legacy automation tokens, but with enhanced security features like expiration dates, scope restrictions, and IP limitations.
49 +
50 +</Note>
51 +
52 ### Authorization only
53
54 If you enable 2FA for authorization only. We will request a second form of authentication only for certain authorized actions.
@@ -67,6 +73,7 @@ If you enable 2FA for authorization only. We will request a second form of authe
73 [deprecate]: https://docs.npmjs.com/cli/deprecate
74 [access]: https://docs.npmjs.com/cli/access
75 [pkg-2fa]: /requiring-2fa-for-package-publishing-and-settings-modification
76 +[granular-tokens]: /integrations/integrating-npm-with-external-services/about-access-tokens#about-granular-access-tokens
77 [webauthn]: https://webauthn.guide/
78 [can-i-use]: https://caniuse.com/#search=webauthn
79 [u2f]: https://en.wikipedia.org/wiki/Universal_2nd_Factor
content/integrations/integrating-npm-with-external-services/about-access-tokens.mdx
+7 -4
@@ -37,23 +37,26 @@ Legacy tokens are created with the same permissions as the user who created them
37
38 There are three different types of legacy tokens:
39
40 -- **Read-only**: You can use these tokens to download packages from the registry. These tokens are best for automation and workflows where you are installing packages. For greater security, we recommend using [granular access tokens](#about-granular-access-tokens) instead.
41 -- **Automation**: You can use these tokens to download packages and install new ones. These tokens are best for automation workflows where you are publishing new packages. Automation tokens do not 2FA for executing operations on npm and are suitable for CI/CD workflows. For greater security, we recommend using [granular access tokens](#about-granular-access-tokens) instead.
40 +- **Read-only**: You can use these tokens to download packages from the registry. These tokens are best for automation and workflows where you are installing packages. For greater security, we recommend using [granular access tokens](#about-granular-access-tokens) instead, which offer fine-grained permissions and configurable expiration.
41 +- **Automation**: You can use these tokens to download packages and install new ones. These tokens are best for automation workflows where you are publishing new packages. Automation tokens automatically bypass 2FA for all operations on npm and are suitable for CI/CD workflows. For greater security and more control, we recommend using [granular access tokens](#about-granular-access-tokens) instead, which allow you to configure 2FA bypass on a per-token basis along with other security features like expiration dates and scope restrictions.
42 - **Publish**: You can use these tokens to download packages, install packages, and update user and package settings. We recommend using them for interactive workflows such as a CLI. If 2FA is enabled on your account, publish tokens will require 2FA to execute sensitive operations on npm.
43
44 Legacy tokens do not have an expiration date. It is important to be aware of your tokens and keep them protected for account security. For more information, see "[Securing your token][secure-token]."
45
46 ## About granular access tokens
47
48 -Granular access tokens allow you to restrict access provided to the token based on what you want to use the token for. With granular access tokens, you can:
48 +Granular access tokens are the modern, recommended token type for npm authentication. They allow you to restrict access provided to the token based on what you want to use the token for. With granular access tokens, you can:
49
50 - Restrict which packages and scopes a token has access to
51 - Grant tokens access to specific organizations
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 +Granular access tokens provide enhanced security compared to legacy automation tokens while maintaining the same flexibility for CI/CD workflows. They can be configured to bypass 2FA requirements when needed, 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, providing the same automation benefits as legacy automation tokens but with additional security controls.
58 +
59 +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.
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
+9 -5
@@ -12,7 +12,7 @@ You can [create](#creating-access-tokens) and [view](#viewing-access-tokens) acc
12
13 <Note>
14
15 -**Note:** For greater security, we recommend using [granular access tokens](#creating-granular-access-tokens-on-the-website) instead of legacy read-only tokens or legacy automation tokens. For CI/CD workflows, consider using [trusted publishing](/trusted-publishers), which eliminates the need for long-lived tokens entirely.
15 +**Note:** For greater security and flexibility, we recommend using [granular access tokens](#creating-granular-access-tokens-on-the-website) instead of legacy tokens. Granular access tokens provide fine-grained permissions, expiration dates, IP restrictions, and configurable 2FA bypass for CI/CD workflows - offering all the benefits of legacy automation tokens with enhanced security controls. For CI/CD workflows, consider using [trusted publishing](/trusted-publishers), which eliminates the need for long-lived tokens entirely.
16
17 </Note>
18
@@ -27,9 +27,9 @@ You can [create](#creating-access-tokens) and [view](#viewing-access-tokens) acc
27 3. (Optional) Name your token.
28
29 4. Select the type of access token:
30 - - **Read-only**: A read-only token can only be used to download packages from the registry. It will have permission to read any private package that you have access to. This is recommended for automation and workflows where you are installing packages, but not publishing new ones.
30 + - **Read-only**: A read-only token can only be used to download packages from the registry. It will have permission to read any private package that you have access to. This is recommended for automation and workflows where you are installing packages, but not publishing new ones. For better security, use [granular access tokens](#creating-granular-access-tokens-on-the-website) which allow you to restrict access to specific packages and set expiration dates.
31
32 - - **Automation**: An automation token can download packages and publish new ones, but if you have two-factor authentication (2FA) configured on your account, it will **not** be enforced. You can use an automation token in continuous integration workflows and other automation systems to publish a package even when you cannot enter a one-time passcode. For enhanced security in CI/CD workflows, consider using [trusted publishing](/trusted-publishers) instead, which eliminates the need for long-lived tokens.
32 + - **Automation**: An automation token can download packages and publish new ones, and it automatically bypasses two-factor authentication (2FA) for all operations on npm. You can use an automation token in continuous integration workflows and other automation systems to publish packages without entering a one-time passcode. **Note:** For enhanced security in CI/CD workflows, we recommend using [granular access tokens](#creating-granular-access-tokens-on-the-website) which allow you to configure 2FA bypass on a per-token basis, set expiration dates, and restrict access to specific packages, or consider using [trusted publishing](/trusted-publishers) which eliminates the need for long-lived tokens entirely.
33
34 - **Publish**: A publish token can perform any action on your behalf, including downloading packages, publishing packages, and changing user settings or package settings. If you have two-factor authentication configured on your account, you will be required to enter a one-time passcode when using a publish token. This is recommended for interactive workflows such as a CLI.
35
@@ -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
+2 -2
@@ -23,7 +23,7 @@ Create a new access token that will be used only to access npm packages from a C
23
24 ### Continuous integration
25
26 -When generating an access token for use in a continuous integration environment, we recommend using a granular access token with limited access to provide greater security.
26 +When generating an access token for use in a continuous integration environment, we recommend using a granular access token with limited access to provide greater security. Granular access tokens allow you to restrict access to specific packages, set expiration dates, and configure IP restrictions.
27
28 If you use a legacy token instead, by default, `npm token create` will generate a token with both read and write permissions. We recommend creating a read-only token:
29
@@ -37,7 +37,7 @@ For more information on creating access tokens, including CIDR-whitelisted token
37
38 For publishing packages in continuous deployment environments, we strongly recommend using [trusted publishing](/trusted-publishers) when available, as it provides enhanced security without requiring token management.
39
40 -If trusted publishing is not available for your CI/CD provider, you may 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.
40 +If trusted publishing is not available for your CI/CD provider, you may create a [granular access token][create-token] configured to bypass 2FA on the website. Granular access tokens provide the same 2FA bypass capability as legacy automation tokens, but with additional security features like expiration dates, scope restrictions, and IP address limitations. Alternatively, you can use a legacy [automation token][create-token], though granular access tokens are recommended for enhanced security. Both token types will allow you to publish even if you have two-factor authentication enabled on your account.
41
42 ### Interactive workflows
43
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 tokens configured to bypass 2FA (such as legacy [automation tokens][creating-automation-token] or [granular access tokens][creating-granular-access-token] with bypass 2FA enabled). This lets you configure tokens in a CI/CD workflow while still requiring two-factor authentication from interactive publishes. We recommend using granular access tokens for enhanced security, as they provide the same 2FA bypass capability as automation tokens but with additional security features like expiration dates and scope restrictions.
10
11 For CI/CD workflows, consider using [trusted publishing](/trusted-publishers), which provides secure, token-free publishing that automatically enforces strong authentication without requiring manual token management.
12
@@ -27,10 +27,10 @@ For CI/CD workflows, consider using [trusted publishing](/trusted-publishers), w
27 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.
28
29 2. **Require two-factor authentication or automation tokens or granular access token**
30 - 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.
30 + 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 a legacy [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. We recommend using granular access tokens for better security, as they provide the same 2FA bypass capability with additional controls like expiration dates and scope restrictions.
31
32 3. **Require two-factor authentication and disallow tokens**
33 - 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.
33 + 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.
34
35 <Screenshot src="/packages-and-modules/securing-your-code/2fa-package-setting.png" alt="Screenshot showing the require two-factor option for a package" />
36