Skip to content

Document granular-only token creation #77

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
nishantms wants to merge 1 commit into from
Closed

Document granular-only token creation #77

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 16 additions & 34 deletions api/registry.npmjs.com/token.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,10 +3,9 @@ paths:
post:
tags:
- Tokens
summary: Create npm access token
summary: Create npm granular access token
description: |
Create a new npm access token with customizable permissions, scope restrictions,
expiration, and CIDR IP range limitations.
Create a new npm granular access token with customizable permissions, scope restrictions, expiration, and CIDR IP range limitations.

**Requirements:**
- Must be authenticated
Expand All @@ -29,12 +28,13 @@ paths:
type: string
pattern: '^Bearer .+'
description: |
Bearer token for authentication. Must be an npm access token.
Bearer token for authentication. Must be an npm session token or a Granular Access Token (GAT) that does not bypass 2FA.

**Format:** `Bearer <token>`

**Accepted token types:**
- npm access token (traditional user token created via `npm login`)
- npm session token created via `npm login`
- Granular Access Token (GAT) with `bypass_2fa: false`
- name: npm-otp
in: header
required: true
Expand Down Expand Up @@ -86,21 +86,13 @@ paths:
oneOf:
- type: number
- type: string
description: 'Expiration in days (number) or ISO date string. Read-write tokens: maximum 90 days, defaults to 7 days. Read-only tokens: unlimited maximum, defaults to 30 days'
description: 'Expiration in days (number) or ISO date string. GATs with any read-write permission have a maximum of 90 days and default to 7 days. GATs with only read permissions have no maximum and default to 30 days'
bypass_2fa:
type: boolean
description: |
Allow token to bypass 2FA requirements for automation
flows such as direct publish.
Marks this granular access token for automation that may bypass 2FA requirements, such as direct publish. This property does not create a separate automation token type.

Tokens created with `bypass_2fa: true` **cannot** perform
account, token, or org/team/package governance write
operations (for example: creating or deleting tokens,
changing package access or trust configuration,
adding/removing org or team members, granting/revoking
team package access, unpublishing). Those requests are
rejected with `403 Forbidden` and must be performed via
an interactive 2FA challenge.
GATs created with `bypass_2fa: true` **cannot** perform account, token, or org/team/package governance write operations (for example: creating or deleting tokens, changing package access or trust configuration, adding/removing org or team members, granting/revoking team package access, unpublishing). Those requests are rejected with `403 Forbidden` and must be performed via an interactive 2FA challenge.
default: false
cidr:
type: array
Expand Down Expand Up @@ -182,10 +174,7 @@ paths:
bypass_2fa:
type: boolean
description: |
Indicates if the token can bypass 2FA requirements for
automation flows. When `true`, the token is rejected
(`403 Forbidden`) by account, token, and org/team/package
governance write endpoints.
Indicates whether this GAT may bypass 2FA requirements for automation flows. This is a property of the GAT, not a separate automation token type. When `true`, the GAT is rejected (`403 Forbidden`) by account, token, and org/team/package governance write endpoints.
revoked:
type: string
format: date-time
Expand Down Expand Up @@ -280,7 +269,7 @@ paths:
value:
error: 'Please select at least one: package, scope or organization.'
expirationLimit:
summary: Expiration exceeds maximum for read-write tokens
summary: Expiration exceeds maximum for a GAT with read-write permissions
value:
error: 'Read-write tokens cannot have expiration longer than 90 days'
"401":
Expand All @@ -301,9 +290,9 @@ paths:
get:
tags:
- Tokens
summary: List npm access tokens
summary: List npm granular access tokens
description: |
List all access tokens associated with the authenticated user's account.
List all granular access tokens associated with the authenticated user's account.

**Requirements:**
- Must be authenticated with a valid Bearer token
Expand All @@ -321,7 +310,7 @@ paths:
type: string
pattern: '^Bearer .+'
description: |
Bearer token for authentication. Must be an npm access token.
Bearer session token for authentication. Must be the npm session token created via `npm login`.

**Format:** `Bearer <token>`
- name: page
Expand All @@ -342,7 +331,7 @@ paths:
- npmSessionToken: []
responses:
"200":
description: "List of tokens retrieved successfully"
description: "List of granular access tokens retrieved successfully"
headers:
npm-notice:
description: |
Expand Down Expand Up @@ -376,17 +365,10 @@ paths:
type: string
description: 'Redacted token in format: npm_aBcD...7890 (first 8 chars + ... + last 4 chars)'
example: npm_aBcD...7890
readonly:
type: boolean
description: Indicates if the token has readonly permissions
bypass_2fa:
type: boolean
description: |
Indicates if the token can bypass 2FA
requirements for automation flows. When `true`,
the token is rejected (`403 Forbidden`) by
account, token, and org/team/package governance
write endpoints.
Indicates whether this GAT may bypass 2FA requirements for automation flows. This is a property of the GAT, not a separate automation token type. When `true`, the GAT is rejected (`403 Forbidden`) by account, token, and org/team/package governance write endpoints.
cidr:
type: array
items:
Expand Down Expand Up @@ -437,7 +419,7 @@ paths:
description: List of scopes this token has access to
total:
type: integer
description: Total number of tokens
description: Total number of granular access tokens
urls:
type: object
description: Pagination URLs for next/previous pages
Expand Down
Loading