OpenAPI Specification
openapi: 3.0.3
info:
title: Verdaccio npm Registry dist-tags tokens 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: tokens
description: API token management
paths:
/-/npm/v1/tokens:
get:
operationId: listTokens
summary: List API tokens
description: Returns all API tokens created by the currently authenticated user.
tags:
- tokens
responses:
'200':
description: List of tokens
content:
application/json:
schema:
$ref: '#/components/schemas/TokenListResponse'
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: createToken
summary: Create an API token
description: 'Creates a new API token for the authenticated user. The plain-text token is returned once; subsequent reads return a masked version.
'
tags:
- tokens
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TokenCreateRequest'
responses:
'200':
description: Newly created token (plain-text, returned once)
content:
application/json:
schema:
$ref: '#/components/schemas/TokenObject'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'501':
description: Storage backend does not support token persistence
/-/npm/v1/tokens/token/{tokenKey}:
delete:
operationId: deleteToken
summary: Revoke an API token
description: Permanently deletes the specified token so it can no longer be used for authentication.
tags:
- tokens
parameters:
- name: tokenKey
in: path
required: true
schema:
type: string
description: The token key identifier (not the token value itself)
responses:
'200':
description: Token revoked successfully
content:
application/json:
schema:
type: object
example: {}
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalError'
components:
schemas:
TokenListResponse:
type: object
properties:
objects:
type: array
items:
$ref: '#/components/schemas/TokenObject'
urls:
type: object
properties:
next:
type: string
description: URL for next page (pagination not yet implemented; always empty)
example: ''
TokenObject:
type: object
properties:
token:
type: string
description: The token value (plain-text on creation; masked on subsequent reads)
example: npm_abc123...
user:
type: string
description: Username that owns the token
example: alice
key:
type: string
description: Unique key identifier for the token
example: a1b2c3d4e5f6789012345678
cidr:
type: array
items:
type: string
description: CIDR restrictions for this token
example: []
cidr_whitelist:
type: array
items:
type: string
description: Alias for cidr, used by npm CLI
example: []
readonly:
type: boolean
description: Whether the token is read-only
example: false
created:
type: string
format: date-time
description: ISO 8601 creation timestamp
example: '2024-01-15T10:30:00.000Z'
ErrorResponse:
type: object
properties:
error:
type: string
description: Human-readable error message
example: package not found
required:
- error
TokenCreateRequest:
type: object
properties:
password:
type: string
format: password
description: User password for re-authentication before token creation
example: s3cr3t
readonly:
type: boolean
description: Whether the token should be read-only
example: false
cidr_whitelist:
type: array
items:
type: string
description: CIDR ranges to restrict token usage
example: []
required:
- password
- readonly
- cidr_whitelist
responses:
InternalError:
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
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