api-documentation/api/base.yaml at main · npm/api-documentation · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
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`

  - 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:
      - Tokens
      - OIDC
      - 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.

    # 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)

    # 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).