npm logo
API docs by Redocly

npm Registry API (1.0.0)

Download OpenAPI specification:

License: MIT

Welcome to the npm registry API documentation!

Introduction

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.

Authentication & Authorization

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, 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

Tokens

Token management endpoints for creating, listing, and deleting npm access tokens.

Create npm access token

Create a new npm access token with customizable permissions, scope restrictions, expiration, and CIDR IP range limitations.

Requirements:

  • Must be authenticated
  • Two-factor authentication is required for this endpoint
    • If 2FA is enabled on your account, provide the OTP via the npm-otp header
    • If 2FA is not enabled, an email OTP will be sent and must be provided via the npm-otp header
    • For WebAuthn users, the OTP is returned in the doneUrl after authentication

Important notices:

  • All responses include security notices via the npm-notice header regarding token limitations
Authorizations:
npmSessionToken
header Parameters
Authorization
required
string^Bearer .+

Bearer token for authentication. Must be an npm access token.

Format: Bearer <token>

Accepted token types:

  • npm access token (traditional user token created via npm login)
npm-otp
required
string

One-time password for two-factor authentication. Always required for this endpoint.

How to obtain the OTP:

  • If 2FA is enabled on your account, provide the OTP from your configured 2FA method
  • If 2FA is not enabled, an email OTP will be sent and must be provided (format: <8-digit-otp-from-email>)
  • For WebAuthn users, the OTP is returned by polling the doneUrl which returns an OTP code after hardware authentication (format: <16-digit-otp>)
npm-auth-type
string
Value: "web"

Authentication type for web-based flow. When set to "web", enables browser-based authentication flow for WebAuthn users.

npm-command
string
Value: "token"

Command context for the request. When set to "token", indicates this is a token creation command.

Request Body schema: application/json
required
password
required
string

User password for authentication

name
required
string

Human-readable name for the token

token_description
string or null

Detailed description of token purpose

number or string

Expiration in days (number) or ISO date string. Read-write tokens: maximum 90 days, defaults to 7 days. Read-only tokens: unlimited maximum, defaults to 30 days

bypass_2fa
boolean
Default: false

Allow token to bypass 2FA requirements

cidr
Array of strings or null

IP ranges that can use this token

packages
Array of strings

Specific packages this token can access. Use ["*"] for all packages. Empty arrays are treated as not provided

scopes
Array of strings

Scoped packages this token can access. Empty arrays are treated as not provided

orgs
Array of strings

Organizations this token can access. Empty arrays are treated as not provided

packages_and_scopes_permission
string
Enum: "read-only" "read-write" "no-access"

Permission for packages and scopes. Defaults to "read-only" if packages/scopes arrays have length > 0, otherwise "no-access"

orgs_permission
string
Enum: "read-only" "read-write" "no-access"

Permission for organizations. Defaults to "read-only" if orgs array has length > 0, otherwise "no-access"

Responses

Request samples

Content type
application/json
{
  • "password": "string",
  • "name": "string",
  • "token_description": "string",
  • "expires": 0,
  • "bypass_2fa": false,
  • "cidr": [
    ],
  • "packages": [
    ],
  • "scopes": [
    ],
  • "orgs": [
    ],
  • "packages_and_scopes_permission": "read-only",
  • "orgs_permission": "read-only"
}

Response samples

Content type
application/json
{
  • "key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  • "name": "string",
  • "description": "string",
  • "token": "npm_aBcDeFgHiJkLmNoPqRsTuVwXyZ1234567890",
  • "expiry": "2019-08-24T14:15:22Z",
  • "cidr": [
    ],
  • "bypass_2fa": true,
  • "revoked": "2019-08-24T14:15:22Z",
  • "created": "2019-08-24T14:15:22Z",
  • "updated": "2019-08-24T14:15:22Z",
  • "accessed": "2019-08-24T14:15:22Z",
  • "permissions": [
    ],
  • "scopes": [
    ]
}

List npm access tokens

List all access tokens associated with the authenticated user's account.

Requirements:

  • Must be authenticated with a valid Bearer token

Response includes:

  • All responses include security notices via the npm-notice header
  • Tokens are redacted for security: format is npm_aBcD...7890 (first 8 chars including prefix + ... + last 4 chars)
  • Supports pagination via query parameters
Authorizations:
npmSessionToken
query Parameters
page
integer
Default: 0

Page number for pagination (0-indexed)

perPage
integer
Default: 10

Number of tokens to return per page

header Parameters
Authorization
required
string^Bearer .+

Bearer token for authentication. Must be an npm access token.

Format: Bearer <token>

Responses

Response samples

Content type
application/json
{
  • "objects": [
    ],
  • "total": 0,
  • "urls": {
    }
}

Delete npm access token

Delete an npm access token. The token can be specified as:

  • A UUID (token identifier)
  • An npm-prefixed token (format: npm_ followed by 36 alphanumeric characters)

Requirements:

  • Must be authenticated with a valid Bearer token
  • May require 2FA OTP depending on user settings

Web authentication flow:

  • When npm-auth-type=web and npm-command=token headers are present and 2FA is required, returns authentication URLs instead of an error
Authorizations:
npmSessionToken
path Parameters
token
required
string

The token identifier to delete. Can be:

  • A UUID (e.g., 12345678-1234-1234-1234-123456789abc)
  • An npm token (e.g., npm_abcdefghijklmnopqrstuvwxyz0123456789)
header Parameters
Authorization
required
string^Bearer .+

Bearer token for authentication. Must be an npm access token.

Format: Bearer <token>

npm-otp
string

One-time password for two-factor authentication. Required if the user has 2FA enabled.

npm-auth-type
string
Value: "web"

Authentication type for web-based flow. When set to "web", enables browser-based authentication flow for WebAuthn users.

npm-command
string
Value: "token"

Command context for the request. When set to "token", indicates this is a token deletion command.

Responses

Response samples

Content type
application/json
Example
{
  • "message": "invalid token"
}

OIDC

OpenID Connect (OIDC) token exchange endpoints for CI/CD integrations.

Exchange OIDC id_token for npm registry token

Exchange a valid OIDC id_token (provided as a Bearer token) for a short-lived npm registry access token for the specified package.

OIDC Token Requirements:

Important: The Bearer token must be an OIDC id_token from an Identity Provider (IdP) npm supports. This endpoint differs from the rest of the API, which expects a standard npm access token.

Authorizations:
oidcIdToken
path Parameters
package_name
required
string

Name of the npm package, url-encoded

Responses

Response samples

Content type
application/json
{
  • "token_type": "oidc",
  • "token": "string",
  • "created": "2025-07-18T10:30:00.000Z",
  • "expires": "2025-07-18T11:30:00.000Z"
}