Use granular access tokens with the smallest package scope, read-only access unless you publish, an expiry date, and an IP range if your network allows it. Leave Bypass 2FA off. Do not keep a long lived publish token in a dotfile on your laptop.
What changed
The npm documentation states that as of November 2025 only granular access tokens are supported, and legacy access tokens have been removed. If you still have an old token in an npmrc file from years ago, check whether it works at all and replace it.
A token is a hexadecimal string that lets you install and or publish packages. Anyone holding the string acts as you, within the token's limits. That is why the limits matter.
The controls npm gives you
From the access token documentation, a granular token can:
- Restrict which packages and scopes it can reach.
- Be tied to specific organizations.
- Have an expiration date, at least one day in the future.
- Be limited by IP address ranges.
- Be read-only or read and write.
- Be set to bypass 2FA, which applies to tokens with write access and is false by default.
Tokens are also bounded by the user's permissions. If your access to a package is revoked, the token loses it too.
Choosing the right shape
- Installing private packages on a laptop: read-only, limited to the scopes you need, with a short expiry.
- Publishing from your laptop: prefer to avoid it. If you must, use a token with an expiry of days, not months.
- Automation: the documentation describes stage-only tokens, which cannot publish a version directly. They stage it for a maintainer with 2FA to review and promote, so a leaked token cannot put a new version on the registry without approval. The documentation calls that a safer on-ramp for CI.
Bypass 2FA, handled carefully
When Bypass 2FA is true it takes precedence over account level and package level 2FA for actions such as publishing. The documentation says not to set it to true if a package or organization requires fully enforced 2FA. For laptop use there is rarely a reason to enable it.
Where tokens end up on a laptop
Check your user and project npmrc files for auth lines. Check shell profiles, env files and CI configuration copied from your machine. If a token is present in more than one place, rotating it means finding every copy.
A cleaner pattern is to pass the token through an environment variable that your shell does not persist, or to use the operating system keychain through a helper script.
Housekeeping routine
- List your tokens in the npm web interface or CLI.
- Delete anything you do not recognize or no longer use.
- Replace long lived tokens with ones that expire.
- Record where each remaining token is used.
If you suspect a token has leaked, revoke it first, then work out what it could do. The documentation notes that you can have up to 1000 granular tokens, so there is no reason to share one across tools.
If you want a quick look at what your projects actually resolve, Safeguard offers SBOM and dependency scanning, and there is a free scan at gold.safeguard.sh/scan.
Quick check
Are legacy npm tokens still supported?
No. The npm documentation says that as of November 2025 only granular access tokens are supported.
What is a stage-only token?
A token that cannot publish directly. It stages a version for a maintainer with 2FA to review and promote.
Sources
Last reviewed: 19 October 2026.
