creating-and-viewing-access-tokens.mdx · cryptotaxi247/documentation

Code Commits Issues Pulls Sessions CI/CD

kartykp/gat-bypass-2fa-docs

@reggi/path-to-regexp dependabot/npm_and_yarn/main/copy-to-clipboard-4.0.2 dependabot/npm_and_yarn/main/eslint-10.4.0 dependabot/npm_and_yarn/main/npmcli/eslint-config-7.0.0 dependabot/npm_and_yarn/main/proc-log-7.0.0 dependabot/npm_and_yarn/npm_and_yarn-826852524d dependabot/npm_and_yarn/npm_and_yarn-ab9a7f4bc2 deprecate-totp-2fa dhei/classic-tokens gat-bypass-2fa-docs jpg619/fix-accessibility-content-flow jpg619/version-bump-tar-2 kartykp/gat-bypass-2fa-docs kartykp/upgrade-path-to-regex main maitxn/version-bump-tar patch-1 reggi/cache-based-on-version reggi/dev-engines reggi/fix-transform-prettier reggi/overrides update-search-sensitivity

mdx 161 lines 10.1 KB

Raw

1	---
2	title: Creating and viewing access tokens
3	redirect_from:
4	- /creating-and-viewing-authentication-tokens
5	---
6
7	You can [create](#creating-access-tokens) and [view](#viewing-access-tokens) access tokens from the website and command line interface (CLI).
8
9	## Creating access tokens
10
11	### Creating legacy tokens on the website
12
13	<Note>
14
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 a modern replacement for 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
19	1. In the upper right corner of the page, click your profile picture, then click Access Tokens.
20
21	<Screenshot src="/integrations/integrating-npm-with-external-services/tokens-profile.png" alt="Screenshot of the account menu with the tokens link selected" />
22
23	2. Click Generate New Token, then select legacy token from the dropdown menu.
24
25	<Screenshot src="/integrations/integrating-npm-with-external-services/create-token.png" alt="Screenshot of the create new token button" />
26
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. 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, 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: Legacy automation tokens are being deprecated. We recommend using [granular access tokens](#creating-granular-access-tokens-on-the-website) with the "Bypass two-factor authentication" option enabled, which provides the same 2FA bypass capability with additional security features like expiration dates and scope restrictions. Alternatively, 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
36	<Screenshot src="/integrations/integrating-npm-with-external-services/token-level-select.png" alt="Screenshot of the access level selection" />
37
38	5. Click Generate Token.
39
40	6. Copy the token from the top of page.
41
42	### Creating granular access tokens on the website
43
44	1. In the upper right corner of the page, click your profile picture, then click Access Tokens.
45
46	<Screenshot src="/integrations/integrating-npm-with-external-services/tokens-profile.png" alt="Screenshot of the account menu with the tokens link selected" />
47
48	2. Click Generate New Token, then click Granular Access Token.
49
50	<Screenshot src="/integrations/integrating-npm-with-external-services/create-token.png" alt="Screenshot of the create new token button" />
51
52	3. In the Token name field, enter a name for your token.
53
54	4. (Optional) In the Description field, enter a description for your token.
55
56	5. In the Expiration field, enter a token expiration period. The date must be at least 1 day in the future.
57
58	6. (Optional) In the Allowed IP Ranges field, enter IP address ranges to restrict your access token to. You must use [CIDR][cidr-wiki] notation to enter IP address ranges. To add more than one allowed IP range, click Add IP Range and enter an IP range in the new text field.
59
60	<Screenshot src="/integrations/integrating-npm-with-external-services/granular-access-token-ip-range.png" alt="Screenshot of the allowed IP ranges section" />
61
62	7. (Optional) In the Packages and scopes section, configure your token's access to packages and scopes.
63	- In the Permissions dropdown menu, select No access, Read-only, or Read and write.
64	- Under Select Packages, select either:
65	- All Packages to grant the token access to all packages the user account has access to.
66	- Only select packages and scopes to choose up to 50 specific packages or scopes to give the token access to. Then select specific packages or scopes from the dropdown menu.
67
68	<Screenshot src="/integrations/integrating-npm-with-external-services/granular-access-token-packages-scopes.png" alt="Screenshot of the packages and scopes section" />
69
70	8. (Optional) In the Organizations section, configure your token's access to organizations.
71	- In the Permissions dropdown menu, select No access, Read-only, or Read and write.
72	- Under Select organizations, select the organizations you want to grant your token access to.
73
74	<Screenshot src="/integrations/integrating-npm-with-external-services/granular-access-token-organizations.png" alt="Screenshot of the organizations section" />
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. (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 useful for CI/CD workflows and automation scenarios.
80	- Leave unchecked if you want the token to respect your account's normal 2FA settings (token will not bypass 2FA).
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
86	11. Copy the token from the top of page.
87
88	### Creating tokens with the CLI
89
90	You can create tokens with read-only permissions or read and publish permissions with the CLI.
91
92	<Note>
93
94	Note: You cannot create legacy automation tokens or granular access tokens from the CLI. You must use the website to generate these types of tokens. For more information, see "[Creating legacy tokens on the website](#creating-legacy-tokens-on-the-website)" and "[Creating granular access tokens on the website](#creating-granular-access-tokens-on-the-website)."
95
96	</Note>
97
98	- Read-only: Tokens that allow installation and distribution only, but no publishing or other rights associated with your account.
99	- Publish: The default setting for new tokens, and most permissive token type. Publish tokens allow installation, distribution, modification, publishing, and all rights that you have on your account.
100
101	In addition, you can specify that the token is only valid for a specific IPv4 address range, using [CIDR][cidr-wiki] notation. The token will only be valid when used from the specified IP addresses.
102
103	1. To create a new token, on the command line, run:
104	- `npm token create` for a read and publish token
105	- `npm token create --read-only` for a read-only token
106	- `npm token create --cidr=[list]` for a CIDR-restricted read and publish token. For example, `npm token create --cidr=192.0.2.0/24`
107	- `npm token create --read-only --cidr=[list]` for a CIDR-restricted read-only token
108	2. When prompted, enter your password.
109	3. If you have enabled [two-factor authentication][tfa], when prompted, enter a one-time password.
110	4. Copy the token from the token field in the command output.
111
112	#### CIDR-restricted token errors
113
114	If the CIDR string you enter is invalid or in an inappropriate format, you will get an error similar to the one below:
115
116	```
117	npm ERR! CIDR whitelist contains invalid CIDR entry: X.X.X.X./YY,Z.Z.. . .
118	```
119
120	Make sure you are using a valid IPv4 range and try creating the token again.
121
122	## Viewing access tokens
123
124	<Note>
125
126	Note: Full tokens are never displayed, only the first and last four characters will be shown. You can only view a full token immediately after creation.
127
128	</Note>
129
130	### Viewing tokens on the website
131
132	To view all tokens associated with your account, in the upper right corner of the page, click your profile picture, then click Access Tokens.
133
134	<Screenshot src="/integrations/integrating-npm-with-external-services/tokens-profile.png" alt="Screenshot of the account menu with the tokens link selected" />
135
136	The token list displays information about each token, including:
137
138	- Token name and value (partially obscured)
139	- Whether the token is configured to bypass two-factor authentication (shows a checkmark for granular access tokens with bypass enabled)
140	- Creation date, last used date, and expiration date
141
142	To view detailed information about a granular access token, including its full permissions, allowed IP ranges, and bypass 2FA configuration, click on the token name.
143
144	### Viewing tokens on the CLI
145
146	To view all tokens associated with your account, on the command line, run the following command:
147
148	```
149	npm token list
150	```
151
152	#### Token attributes
153
154	- id: Use the token ID to refer to the token in commands.
155	- token: The first digits of the actual token.
156	- create: Date the token was created.
157	- readonly: If yes, indicates a read-only token. If no, indicates a token with both read and publish permissions.
158	- CIDR whitelist: Restricts token use by IP address.
159
160	[tfa]: about-two-factor-authentication
161	[cidr-wiki]: https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing