A good registry token policy sets an expiry, limits scope to named packages or repositories, separates read from write, restricts source addresses, and ties the token to its owner's rights. npm's current token documentation shows each of these controls in practice and makes a useful checklist for your own registry.
What npm documents today
The npm documentation says granular access tokens are the supported type, and that legacy tokens were removed as of November 2025. For those tokens:
- You set the validity period, with expiry at least one day ahead.
- You can limit a token to specific packages, scopes and organisations, up to 50 of each kind.
- Tokens are read only or read and write.
- For write, direct publishing and stage only are separate options. Stage only tokens can stage a version for maintainer review but cannot publish directly.
- Tokens can be restricted to IP ranges in CIDR form.
- A token cannot exceed the permissions of the user who owns it. If the user loses access, the token does too.
- A bypass 2FA option exists for write tokens, off by default, and the docs advise against it where 2FA is fully enforced.
The page also says direct publishing with granular tokens is scheduled for removal in January 2027 and recommends stage only tokens or trusted publishing for CI. Check the page before relying on dates, since they may change.
Turning that into your own policy
| Control | What to write down |
|---|---|
| Expiry | A maximum lifetime, such as ninety days, and a rotation owner |
| Scope | One token per pipeline, limited to the repositories it needs |
| Read or write | Read only by default; write needs a reason |
| Source address | CIDR limits for CI runners and build networks |
| Owner link | Tokens die when the person or service account is disabled |
| Review step | Publishing goes through a staged or approved path where possible |
Rules that follow
- No personal tokens in CI. Create a service identity with narrow rights.
- No tokens without an expiry. A forgotten token is a standing key.
- No shared tokens across teams. When one leaks you cannot tell which pipeline did it.
- No write tokens on developer laptops when a pipeline can publish.
- Log every token creation and use. Answer who made it, when, and what it touched.
- Test revocation. Pick a token, revoke it, and see how long until clients fail.
What to do when one leaks
Revoke it first, then read the access log for what it did between exposure and revocation. Check for published versions, deleted artifacts and reads of private packages. Replace the token with a new narrower one.
Why this matters for a self-hosted registry
A self-hosted registry gives you the job of deciding and enforcing the policy with the features your software has. If it cannot express scope or expiry, put the control in a proxy, or in the secret manager that issues the tokens.
Safeguard's policies and gates can enforce rules in your pipeline, and the free scan is at gold.safeguard.sh/scan.
Try it yourself
Click through it at your own pace, or open it full screen.
Click through the demo and watch how a result ties back to a specific artifact, which is what you want from any registry you run.
Quick check
Should CI tokens be read only?
For installs, yes. Give write rights only to the pipeline that publishes, and keep that token narrow and short lived.
Do I still need rotation if tokens expire?
Yes. Expiry only helps if someone replaces the token before it lapses, so assign an owner and an alert.
Sources
Last reviewed: 19 October 2026.
