npm Tokens API

openapi: 3.2.0
info:
  title: Npm Tokens API
  version: 1.0.0
  x-refined-note:
  - x-logo differs across the merged source definitions and was not carried
  - x-source differs across the merged source definitions and was not carried
  description: 'Operations tagged Tokens across 3 of this provider''s published API definitions: npm-public-api-openapi.yml, npm-registry-reference-openapi.json, npm-registry-reference-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://registry.npmjs.org
  description: npm Public Registry
tags:
- name: Tokens
  description: Manage npm access tokens for authentication. Create, list, and delete tokens with customizable permissions and restrictions.
paths:
  /-/npm/v1/tokens:
    get:
      operationId: listTokens
      summary: List access tokens
      description: Retrieves a list of the authenticated user's active npm access tokens. Token UUIDs are redacted in the response, but each token object includes a key attribute containing the hexadecimal SHA-512 hash of the token for identification purposes.
      tags:
      - Tokens
      parameters:
      - name: page
        in: query
        description: Page number for paginated results.
        required: false
        schema:
          type: integer
          minimum: 0
      - name: perPage
        in: query
        description: Number of tokens to return per page.
        required: false
        schema:
          type: integer
          minimum: 1
      responses:
        '200':
          description: List of tokens retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  objects:
                    type: array
                    description: List of token objects.
                    items:
                      $ref: '#/components/schemas/Token'
                  total:
                    type: integer
                    description: Total number of tokens.
                  urls:
                    type: object
                    description: Pagination URLs.
                    properties:
                      next:
                        type: string
                        description: URL for the next page of results.
        '401':
          description: Authentication required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - bearerAuth: []
    post:
      operationId: createToken
      summary: Create an access token
      description: Creates a new npm access token with customizable permissions, scope restrictions, expiration settings, and CIDR IP range limitations. The response includes the full token value, which is only returned once and cannot be retrieved again.
      tags:
      - Tokens
      parameters:
      - name: npm-otp
        in: header
        description: One-time password for accounts with two-factor authentication enabled.
        required: false
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenCreateRequest'
      responses:
        '200':
          description: Token created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenWithValue'
        '400':
          description: Invalid request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - bearerAuth: []
    servers:
    - url: https://registry.npmjs.org
      description: npm Public Registry
  /-/npm/v1/tokens/token/{token_id}:
    delete:
      operationId: deleteToken
      summary: Delete an access token
      description: Deletes an npm access token by its identifier. Note that the token may remain valid in cache for up to one hour after deletion.
      tags:
      - Tokens
      parameters:
      - name: token_id
        in: path
        description: The token key hash or UUID identifying the token to delete.
        required: true
        schema:
          type: string
      - name: npm-otp
        in: header
        description: One-time password for accounts with two-factor authentication enabled.
        required: false
        schema:
          type: string
      responses:
        '204':
          description: Token deleted successfully.
        '401':
          description: Authentication required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Token not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - bearerAuth: []
    servers:
    - url: https://registry.npmjs.org
      description: npm Public Registry
  /-/npm/v1/tokens/token/{token}:
    delete:
      tags:
      - Tokens
      summary: Delete npm access token
      description: 'Delete an npm access token. The token can be specified as:

        - A UUID (token identifier)

        - An npm-prefixed token (format: `npm_` followed by 36 alphanumeric characters)


        **Requirements:**

        - Must be authenticated with a valid Bearer token

        - May require 2FA OTP depending on user settings

        - **Granular Access Tokens with `bypass_2fa: true` are not permitted**

        to call this endpoint and receive `403 Forbidden`. Token deletion

        requires an interactive 2FA challenge.


        **Web authentication flow:**

        - When `npm-auth-type=web` and `npm-command=token` headers are present and 2FA is required,

        returns authentication URLs instead of an error'
      operationId: deleteNpmV1TokensTokenByToken
      parameters:
      - name: token
        in: path
        required: true
        schema:
          type: string
        description: 'The token identifier to delete. Can be:

          - A UUID (e.g., `12345678-1234-1234-1234-123456789abc`)

          - An npm token (e.g., `npm_abcdefghijklmnopqrstuvwxyz0123456789`)

          '
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
          pattern: ^Bearer .+
        description: 'Bearer token for authentication. Must be an npm access token.


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

          '
      - name: npm-otp
        in: header
        required: false
        schema:
          type: string
        description: 'One-time password for two-factor authentication. Required if the user has 2FA enabled.

          '
      - name: npm-auth-type
        in: header
        required: false
        schema:
          type: string
          enum:
          - web
        description: 'Authentication type for web-based flow. When set to "web", enables

          browser-based authentication flow for WebAuthn users.

          '
      - name: npm-command
        in: header
        required: false
        schema:
          type: string
          enum:
          - token
        description: 'Command context for the request. When set to "token", indicates

          this is a token deletion command.

          '
      security:
      - npmSessionToken: []
      - npmAccessToken: []
      - granularAccessToken: []
      responses:
        '204':
          description: Token deleted successfully
          headers:
            npm-notice:
              description: 'Security notice regarding token limitations.

                '
              schema:
                type: string
          content: {}
        '400':
          description: Bad request - Invalid token format or token not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              examples:
                invalidToken:
                  summary: Invalid token format
                  value:
                    message: invalid token
                notFound:
                  summary: Token not found when searching by hash
                  value:
                    message: could not delete token
        '401':
          description: Unauthorized - Invalid authentication or missing OTP
          headers:
            www-authenticate:
              description: Authentication challenge (e.g., "OTP" when OTP is required)
              schema:
                type: string
            npm-notice:
              description: Additional notice information
              schema:
                type: string
          content:
            application/json:
              schema:
                oneOf:
                - type: object
                  description: Error response for missing authentication or OTP
                  properties:
                    error:
                      type: string
                  required:
                  - error
                - type: object
                  description: Web authentication flow response
                  properties:
                    authUrl:
                      type: string
                      format: uri
                      description: URL to authenticate via web browser
                    doneUrl:
                      type: string
                      format: uri
                      description: URL to poll for completion of authentication
                  required:
                  - authUrl
                  - doneUrl
              examples:
                unauthorized:
                  summary: No Authorization header provided
                  value:
                    error: Unauthorized
                invalidOtp:
                  summary: Invalid OTP provided
                  value:
                    error: invalid OTP
                web_auth_flow:
                  summary: Web authentication flow (2FA required)
                  description: 'When user has 2FA enabled and includes both `npm-auth-type=web` and `npm-command=token` headers.

                    '
                  value:
                    authUrl: https://www.npmjs.com/auth/cli/00000000-0000-0000-0000-000000000000
                    doneUrl: https://registry.npmjs.org/-/v1/done?authId=00000000-0000-0000-0000-000000000000
        '403':
          $ref: '#/components/responses/Forbidden2FABypassGAT'
        '404':
          description: Not found - Token does not exist
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
      x-operation-id-source: normalized
      x-operation-id-original: deleteToken
    servers:
    - url: https://registry.npmjs.org
components:
  schemas:
    TokenWithValue:
      type: object
      description: An npm access token including the full token value. The token value is only returned once at creation time and cannot be retrieved again.
      allOf:
      - $ref: '#/components/schemas/Token'
      - type: object
        properties:
          token:
            type: string
            description: The full token UUID value. This is only returned at creation time.
    TokenCreateRequest:
      type: object
      description: Request body for creating a new npm access token.
      required:
      - password
      properties:
        password:
          type: string
          description: The user's npm account password, required to authorize token creation.
        readonly:
          type: boolean
          description: Set to true to create a read-only token.
          default: false
        automation:
          type: boolean
          description: Set to true to create an automation token that bypasses two-factor authentication for publishing.
          default: false
        cidr_whitelist:
          type: array
          description: List of CIDR IP ranges to restrict where this token can be used from.
          items:
            type: string
            pattern: ^[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+/[0-9]+$
    Error:
      type: object
      description: An error response from the npm API.
      properties:
        error:
          type: string
          description: The error type or code.
        message:
          type: string
          description: A human-readable description of the error.
    Token:
      type: object
      description: An npm access token with its metadata. The actual token value is redacted; only the key hash is provided.
      properties:
        key:
          type: string
          description: The hexadecimal SHA-512 hash of the token, used for identification.
        token:
          type: string
          description: A redacted representation of the token UUID.
        cidr_whitelist:
          type: array
          description: List of CIDR IP ranges that are allowed to use this token. Null if no restrictions are set.
          items:
            type: string
        readonly:
          type: boolean
          description: Whether this token has read-only access.
        automation:
          type: boolean
          description: Whether this token is an automation token that bypasses two-factor authentication requirements for publishing.
        created:
          type: string
          format: date-time
          description: The date and time the token was created.
        updated:
          type: string
          format: date-time
          description: The date and time the token was last updated.
  responses:
    UnauthorizedWithWebAuth:
      description: 'Unauthorized - Authentication scenarios based on 2FA status and header presence.


        **Authentication Scenarios:**


        1. **No Authorization header**: Returns generic "Unauthorized" error when no Bearer token is provided or the token is invalid

        2. **No 2FA enabled + npm-otp header omitted**: Returns error requesting email OTP. An email is automatically sent to the user''s registered email address

        3. **2FA enabled + npm-otp header omitted (legacy flow)**: Returns 2FA error with npm-notice header containing WebAuthn URL. This is for older CLI versions without web auth support

        4. **2FA enabled + npm-otp header omitted (web auth flow)**: Returns authentication URLs (authUrl and doneUrl) when both npm-auth-type=web and npm-command=token headers are present

        '
      headers:
        npm-notice:
          description: 'Notice header sent when 2FA is enabled and web auth headers are not present.

            Contains URL for WebAuthn security key authentication.

            '
          schema:
            type: string
          example: Open https://www.npmjs.com/login/<uuid> to use your security key for authentication
      content:
        application/json:
          schema:
            oneOf:
            - type: object
              description: Error response for missing authentication or OTP
              properties:
                error:
                  type: string
              required:
              - error
            - type: object
              description: Web authentication flow response
              properties:
                authUrl:
                  type: string
                  format: uri
                  description: URL to authenticate via web browser
                doneUrl:
                  type: string
                  format: uri
                  description: URL to poll for completion of authentication
              required:
              - authUrl
              - doneUrl
          examples:
            unauthorized:
              summary: No Authorization header provided
              description: 'When no Authorization header is provided or the token is invalid.

                '
              value:
                error: Unauthorized
            no_2fa_missing_otp:
              summary: No 2FA enabled + npm-otp header omitted
              description: 'When user has no 2FA enabled and omits the `npm-otp` header.


                An email OTP is automatically sent to the user''s registered email address.

                The user should check their email and retry the request with the received OTP.

                '
              value:
                error: A One Time Password (OTP) by email is required.
            with_2fa_missing_otp:
              summary: 2FA enabled + npm-otp header omitted (legacy flow)
              description: 'When user has 2FA enabled, omits the `npm-otp` header, and doesn''t include web auth headers. This is a legacy notice supported in older versions of the CLI without support for `npm-auth-type=web`.


                **Response includes npm-notice header:**


                > `npm-notice: Open https://www.npmjs.com/login/<uuid> to use your security key for authentication`

                '
              value:
                error: You must provide a one-time pass. Upgrade your client to npm@latest in order to use 2FA.
            web_auth_flow:
              summary: 2FA enabled + npm-otp header omitted (web auth flow)
              description: 'When user has 2FA enabled, omits the `npm-otp` header, and includes both `npm-auth-type=web` and `npm-command=token` headers.

                '
              value:
                authUrl: https://www.npmjs.com/auth/cli/00000000-0000-0000-0000-000000000000
                doneUrl: https://registry.npmjs.org/-/v1/done?authId=00000000-0000-0000-0000-000000000000
    Forbidden2FABypassGAT:
      description: 'Forbidden: bypass-2FA GAT not permitted for account or governance writes'
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                description: Error message
          example:
            error: 'Granular access tokens that bypass two-factor authentication may not perform this action. For more info, visit: https://gh.io/npm-gat-bypass2fa-deprecation'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: npm access token provided as a Bearer token. Supports both classic tokens and granular access tokens.
    basicAuth:
      type: http
      scheme: basic
      description: Basic authentication using npm username and password.
    oidcBearerAuth:
      type: http
      scheme: bearer
      description: OIDC identity token from a supported CI/CD provider, provided as a Bearer token for token exchange.
    oidcIdToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'OIDC id_token from a supported Identity Provider (IdP) such as GitHub Actions, GitLab CI, or CircleCI.

        The `aud` (audience) claim must be set to `npm:registry.npmjs.org`.


        **Supported Identity Providers:**

        - GitHub Actions

        - GitLab CI

        - CircleCI

        '
    npmSessionToken:
      type: http
      scheme: bearer
      description: 'Traditional npm session token created via `npm login`.

        These tokens are tied to a user account and inherit the user''s permissions.

        '
    npmAccessToken:
      type: http
      scheme: bearer
      description: 'Granular Access Token (GAT) with fine-grained permissions.

        These tokens can be scoped to specific packages and operations.


        GATs created with `bypass_2fa: true` cannot perform account,

        token, or org/team/package governance write operations — those

        requests are rejected with `403 Forbidden`. See the Authentication

        section above for the full list.

        '
    granularAccessToken:
      type: http
      scheme: bearer
      description: 'Granular Access Token (GAT) with fine-grained permissions.

        These tokens can be scoped to specific packages and operations.

        (Alias for npmAccessToken)


        GATs created with `bypass_2fa: true` cannot perform account,

        token, or org/team/package governance write operations — those

        requests are rejected with `403 Forbidden`.

        '
    oidcExchangeToken:
      type: http
      scheme: bearer
      description: 'Short-lived npm registry token obtained by exchanging an OIDC id_token

        via the `/oidc/token/exchange` endpoint. These tokens are package-scoped

        and have limited lifetime (typically 1 hour).

        '
externalDocs:
  description: npm Public API Documentation
  url: https://api-docs.npmjs.com/
x-refined-from:
- npm-public-api-openapi.yml
- npm-registry-reference-openapi.json
- npm-registry-reference-openapi.yml