Effectively manage access to your private packages on NPM

Orbay Yeşil
3 min readJan 23, 2023

NPM released the beta version of Granular Access Token a few weeks ago and I am going to tell you about the advantages of this new feature.

The “Granular Access Token” Option

What does “token” on NPM?

First of all, let’s explain what a token is in NPM.

As you know (I guess you know if you are reading this article), NPM (Node Package Manager) is a package manager for JavaScript, and npmjs.com is the default registry to install the depended packages into your Node.js project.

The majority of well-known packages like TypeScript are public packages and they can be installed from everyone without the permission of the owner of the packages. However, you need to publish your packages as private to NPM under your organization if you want to store and distribute your packages privately.

Your packages are not installable by everyone when they are labelled as private. But, on the other hand, you may want your private packages can be installed by only some people who you authorized. You can create an auth token and give your consumers this token, and the consumers use it to install your packages.

Your consumers add these 2 lines on their “.npmrc” file and by this way they make your packages installable.

If they want to install as a tarball, they should add this token in the authorization header

As you can see, there are two parameters:
- YOUR_ORGANIZATION_ON_NPM: It is your organization name on npmjs.com.
- YOUR_NPM_TOKEN: This is the auth token which is mentioned above.

You can create many tokens under your organization and provide each token usable by different consumers.

What is the “Granular Access Token”?

We figured out what the auth token does on NPM. Now, it is time to talk about the new Granular Access Token.

Imagine that you have many private packages, and you want to distribute different packages to different consumers. That is, you do not want every consumer to have access to all of your private packages.

Classic Tokens (also known as ‘legacy tokens’ now) are not eligible to manage this situation. You can create these types of classic tokens:

  • Read-only: A read-only token can download public or private packages from the npm registry.
  • Automation: An automation token will bypass two-factor authentication (2FA) when publishing. If you have 2FA enabled, you will not be prompted when using an automation token, making it suitable for CI/CD workflows.
  • Publish: A publish token can read and publish packages to the npm registry. If you have 2FA enabled, it will be required when using this token.

With a classic token, you cannot do these listed under:

  • Restrict which packages and scopes a token has access to
  • Grant tokens access to specific organizations
  • Set a token expiration date
  • Limit token access based on IP address ranges

However, you can do them all with a Granular Access Token!

Are there any limits?

There are some limits about Granular Access Tokens:

  • up to 50 granular access tokens can be creatable on your npm account
  • maximum expiration cannot be longer than 365 days
  • each token can access up to 50 organizations, and up to either 50 packages, 50 scopes, or a combination of 50 packages and scopes


Although the Granular Access Token provides you a great way to manage the accessibility of your private packages, the limits may be frustrating if you have many different consumers and need to manage the accessibilities for many private packages.

If you are a big company or an organization or think it will grow in the future, I personally recommend you that you should split your packages to different npm accounts.

Thanks so much for reading!