openapi: 3.0.3
info:
  title: Verdaccio npm Registry dist-tags user API
  description: 'The Verdaccio npm Registry REST API implements the CommonJS Compliant Package Registry specification, providing endpoints to publish, retrieve, search, and delete npm packages. It supports JWT tokens and Basic Auth for authentication and mirrors the standard npm registry protocol so any npm, yarn, or pnpm client can interact with it without modification.

    '
  version: 6.0.0
  contact:
    name: Verdaccio Community
    url: https://discord.gg/7qWJxBf
  license:
    name: MIT
    url: https://github.com/verdaccio/verdaccio/blob/master/LICENSE
  x-api-id: verdaccio:verdaccio-npm-registry-api
servers:
- url: http://localhost:4873
  description: Default local Verdaccio instance
security:
- bearerAuth: []
- basicAuth: []
tags:
- name: user
  description: User authentication and management
paths:
  /-/whoami:
    get:
      operationId: whoami
      summary: Get current authenticated user name
      description: Returns the username of the currently authenticated user. Equivalent to `npm whoami`.
      tags:
      - user
      responses:
        '200':
          description: Username of the authenticated user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WhoamiResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /-/user/{org_couchdb_user}:
    get:
      operationId: getUser
      summary: Get user information
      description: Returns authenticated user information. Used by npm to verify login status.
      tags:
      - user
      parameters:
      - $ref: '#/components/parameters/OrgCouchdbUser'
      responses:
        '200':
          description: User information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    put:
      operationId: addOrLoginUser
      summary: Add a new user or log in an existing user
      description: 'Creates a new user account or authenticates an existing user. This is the endpoint used by `npm login` / `npm adduser`. Returns a JWT or Basic Auth token on success.

        '
      tags:
      - user
      parameters:
      - $ref: '#/components/parameters/OrgCouchdbUser'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserLoginRequest'
      responses:
        '201':
          description: User created or authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserLoginResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          description: Username conflict
  /-/v1/login:
    post:
      operationId: initiateLogin
      summary: Initiate web login flow
      description: 'Starts the web-based login flow. Available only when the `webLogin` feature flag is enabled. Returns a login URL and session token.

        '
      tags:
      - user
      security: []
      responses:
        '200':
          description: Login URL and session details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginInitiateResponse'
  /-/v1/login_cli/{sessionId}:
    get:
      operationId: pollLoginSession
      summary: Poll web login session status
      description: Polls the status of a web login session by session ID.
      tags:
      - user
      security: []
      parameters:
      - name: sessionId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Session status
          content:
            application/json:
              schema:
                type: object
  /-/v1/done:
    get:
      operationId: completeLogin
      summary: Complete web login flow
      description: Finalizes the web login and issues an authentication token.
      tags:
      - user
      responses:
        '200':
          description: Authentication completed
          content:
            application/json:
              schema:
                type: object
  /-/v1/done/{sessionId}:
    get:
      operationId: completeLoginSession
      summary: Complete web login flow for a specific session
      description: Finalizes the web login for a specific session ID.
      tags:
      - user
      parameters:
      - name: sessionId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Authentication completed
          content:
            application/json:
              schema:
                type: object
components:
  schemas:
    UserLoginResponse:
      type: object
      properties:
        ok:
          type: string
          example: user 'alice' created
        token:
          type: string
          description: JWT or Basic Auth token to use in subsequent requests
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
      required:
      - ok
      - token
    WhoamiResponse:
      type: object
      properties:
        username:
          type: string
          description: Username of the authenticated user
          example: alice
      required:
      - username
    UserResponse:
      type: object
      properties:
        name:
          type: string
          description: Username
          example: alice
        email:
          type: string
          format: email
          description: Email address (may be empty)
          example: ''
        ok:
          oneOf:
          - type: string
          - type: boolean
          description: Authentication status message or boolean
          example: you are authenticated as 'alice'
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Human-readable error message
          example: package not found
      required:
      - error
    UserLoginRequest:
      type: object
      properties:
        _id:
          type: string
          description: CouchDB user document ID
          example: org.couchdb.user:alice
        name:
          type: string
          description: Username
          example: alice
        password:
          type: string
          format: password
          description: Plain-text password
          example: s3cr3t
        type:
          type: string
          enum:
          - user
          example: user
        roles:
          type: array
          items:
            type: string
          example: []
        date:
          type: string
          format: date-time
          example: '2024-01-15T10:30:00.000Z'
      required:
      - name
      - password
    LoginInitiateResponse:
      type: object
      properties:
        loginUrl:
          type: string
          format: uri
          description: URL the user should open in a browser to authenticate
          example: http://localhost:4873/-/v1/login_cli/abc123
        doneUrl:
          type: string
          format: uri
          description: URL to poll for login completion
          example: http://localhost:4873/-/v1/done/abc123
  parameters:
    OrgCouchdbUser:
      name: org_couchdb_user
      in: path
      required: true
      schema:
        type: string
      description: CouchDB-style user identifier, e.g. `org.couchdb.user:alice`
      example: org.couchdb.user:alice
  responses:
    Unauthorized:
      description: Authentication required or credentials are invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Bad request — missing or invalid parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token issued by Verdaccio on login
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic Auth with registry username and password