openapi: 3.1.0
info:
  title: npm Hooks Downloads Tokens API
  description: The npm Hooks API allows developers to subscribe to notifications about changes in the npm registry. Hooks send HTTP POST payloads to a configured URI whenever a package is changed, enabling developers to build integrations that respond to registry events in real time. Users can add hooks to follow specific packages, track all activity of given npm users, or monitor all packages within an organization or user scope. The API provides endpoints for creating, listing, updating, and deleting hook subscriptions. Note that npm hooks services have been deprecated as of July 2024.
  version: 1.0.0
  contact:
    name: npm Support
    url: https://www.npmjs.com/support
  termsOfService: https://docs.npmjs.com/policies/terms
servers:
- url: https://registry.npmjs.org
  description: npm Public Registry
security:
- bearerAuth: []
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'
    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'
  /-/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'
components:
  schemas:
    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]+$
    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.
    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.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: npm access token provided as a Bearer token.
externalDocs:
  description: npm Hooks Documentation
  url: https://blog.npmjs.org/post/145260155635/introducing-hooks-get-notifications-of-npm