base.yaml

openapi: 3.1.0
info:
  title: npm Registry API
  version: 1.0.0
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  description: |
    Welcome to the npm registry API documentation!
  x-logo:
    url: |
      data:image/png;base64,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
    altText: npm logo
servers:
  - url: https://registry.npmjs.org

tags:
  - name: Introduction
    x-displayName: Introduction
    description: |
      This is the API documentation for the npm registry. For information about the npm registry, website, and command-line interface (CLI), please refer to [https://docs.npmjs.com](https://docs.npmjs.com).

  - name: Authentication
    x-displayName: Authentication & Authorization
    description: |
      The npm registry API supports multiple types of bearer tokens for authentication:

      **Token Types:**

      **1. npm Session Token (`npmSessionToken`)**
      Traditional npm session tokens created via `npm login`. These tokens:
      - Are tied to a user account
      - Inherit the user's permissions
      - Have limited expiration
      - **Required for:** User account management, token creation/management

      **2. npm Access Token (`npmAccessToken`)**
      Fine-grained tokens with specific permissions:
      - Can be scoped to specific packages and organizations
      - Can be scoped to specific operations (read, write, publish)
      - Have configurable expiration
      - **Supported for:** Most package operations where explicitly documented

      **3. OIDC id_token (`oidcIdToken`)**
      Tokens from supported Identity Providers (CI/CD systems):
      - From GitHub Actions, GitLab CI, CircleCI, etc.
      - Must have `aud` claim set to `npm:registry.npmjs.org`
      - Short-lived tokens
      - **Required for:** OIDC token exchange only

      **4. OIDC Exchange Token (`oidcExchangeToken`)**
      Short-lived tokens obtained from OIDC token exchange:
      - Package-scoped permissions
      - Limited lifetime (typically 1 hour)
      - **Supported for:** Package publishing and management operations

      **Endpoint Authorization:**

      Each endpoint specifies which token types are accepted via security schemes.
      Some endpoints may accept multiple token types, others are restricted to specific types.

      **Example:**
      - `/tokens` endpoint: Only accepts `npmSessionToken`
      - `/oidc/token/exchange` endpoint: Only accepts `oidcIdToken`
      - Package publishing: May accept `npmSessionToken`, `npmAccessToken`, or `oidcExchangeToken`

      **Granular Access Tokens with `bypass_2fa`:**

      Granular Access Tokens (GATs) created with `bypass_2fa: true` are
      allowed to perform automation flows such as direct publish, but they
      are **not** permitted to perform account-identity or governance write
      operations. Requests to those endpoints authenticated with a
      bypass-2FA GAT are rejected with `403 Forbidden` and must instead be
      performed via an interactive 2FA challenge (npm website, or an npm
      session token / non-bypass GAT with a valid `npm-otp`).

      Operations rejected for bypass-2FA GATs include (non-exhaustive):

      - Token management — `POST /-/npm/v1/tokens`, `DELETE /-/npm/v1/tokens/token/{token}`
      - Account settings — change password, change email, change 2FA
        configuration, generate recovery codes, update profile
      - Package governance — `POST /-/package/{escapedPackageName}/access`,
        `POST /-/package/{package}/trust`,
        `DELETE /-/package/{package}/trust/{config-uuid}`,
        maintainer edits, and package/binary deletion (unpublish)
      - Org and team governance —
        `PUT`/`DELETE /-/org/{orgName}/user`,
        `PUT /-/org/{orgName}/team`,
        `DELETE /-/org/{orgName}/{teamName}`,
        `PUT`/`DELETE /-/org/{orgName}/{teamName}/user`,
        `PUT`/`DELETE /-/team/{orgName}/{teamName}/package`

      Direct publish (`PUT /{escapedPackageName}`) remains functional for
      bypass-2FA GATs.

  - name: Tokens
    x-displayName: Tokens
    description: |
      Token management endpoints for creating, listing, and deleting npm access tokens.

  - name: OIDC
    x-displayName: OIDC
    description: |
      OpenID Connect (OIDC) token exchange endpoints for CI/CD integrations.

  - name: Trust
    x-displayName: Trust
    description: |
      Trust-related endpoints for managing package trust and security settings.

x-tagGroups:
  - name: Introduction
    tags:
      - Introduction
  - name: Authentication & Authorization
    tags:
      - Authentication
  - name: Sections
    tags:
      - Access
      - Audit
      - OIDC
      - Org
      - Publish
      - Search
      - Stage
      - Team
      - Tokens
      - Trust

components:
  securitySchemes:
    # OIDC id_token from supported Identity Providers (GitHub Actions, GitLab CI, etc.)
    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

    # Traditional npm user access tokens
    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.

    # Granular Access Tokens (GAT) - fine-grained tokens with specific 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.

    # Alias for npmAccessToken - for backward compatibility
    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`.

    # Short-lived tokens obtained from OIDC token exchange
    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).