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

Access

Get all packages for a team

Get all of the packages a team has access to, as well as the access level that team has for each package.

Authorizations:
npmSessionToken
path Parameters
orgName
required
string

Name of an org

teamName
required
string

Name of a team

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)

Responses

Response samples

Content type
application/json
{
  • "@npmcli/arborist": "read-write",
  • "@npmcli/config": "read-only"
}

Grant access to a package for a team

Authorizations:
npmSessionToken
path Parameters
orgName
required
string

Name of an org

teamName
required
string

Name of a team

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)
Request Body schema: application/json
required
package
string

The name of the package to give access to

permissions
string
Enum: "read-only" "read-write"

The access level of the package to grant to the team

Responses

Request samples

Content type
application/json
{
  • "package": "string",
  • "permissions": "read-only"
}

Response samples

Content type
application/json
{
  • "error": "Missing \"Bearer\" header."
}

Remove access to a package for a team

Authorizations:
npmSessionToken
path Parameters
orgName
required
string

Name of an org

teamName
required
string

Name of a team

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)

Responses

Response samples

Content type
application/json
{
  • "error": "Missing \"Bearer\" header."
}

Get all packages for an org

Get all of the packages an org has access to, as well a the access level that org has for each pacakge.

Authorizations:
npmSessionToken
path Parameters
orgName
required
string

Name of an org

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)

Responses

Response samples

Content type
application/json
{
  • "@npmcli/arborist": "read-write",
  • "@npmcli/config": "read-only"
}

Get all of the users that have access to a package, as well as the access level that user has for each package.

Authorizations:
npmSessionToken
path Parameters
escapedPackageName
required
string
Example: @npmcli%2Farborist

The name of a package. Scoped packages need "/" to be url encoded to "%2F"

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)

Responses

Response samples

Content type
application/json
{
  • "npm": "read-write",
  • "microsoft": "read-only"
}

Get the visibility of a package.

Authorizations:
npmSessionToken
path Parameters
escapedPackageName
required
string
Example: @npmcli%2Farborist

The name of a package. Scoped packages need "/" to be url encoded to "%2F"

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)

Responses

Response samples

Content type
application/json
{
  • "@npmcli/arborist": "public",
  • "@npmcli/hidden": "private"
}

Sets the various access levels for a package.

Authorizations:
npmSessionToken
path Parameters
escapedPackageName
required
string
Example: @npmcli%2Farborist

The name of a package. Scoped packages need "/" to be url encoded to "%2F"

Request Body schema: application/json
required
access
string
Enum: "public" "private"

Visibility of a package

publish_requires_tfa
boolean

Whether publishing this package requires multifactor auth

automation_token_overrides_tfa
boolean

Whether or not automation tokens override the requirement for multifactor auth

Responses

Request samples

Content type
application/json
{
  • "access": "public",
  • "publish_requires_tfa": true,
  • "automation_token_overrides_tfa": true
}

Response samples

Content type
application/json
{
  • "error": "Missing \"Bearer\" header."
}

Audit

Get advisories for packages

Get advisories for a list of packages and version ranges

Request Body schema: application/json
required

Packages with their versions

@npm/example-package*
additional property
Array of strings

Array of versions for this package

Responses

Request samples

Content type
application/json
{
  • "@npmcli/arborist": [
    ],
  • "@npmcli/config": [
    ]
}

Response samples

Content type
application/json
{
  • "@npm/example-package1": [
    ],
  • "@npm/example-package2": [
    ]
}

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"
}

Org

Get users in an org

Get all of the users in an org, along with their access levels in that org

Authorizations:
npmSessionToken
path Parameters
orgName
required
string

Name of an org

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)

Responses

Response samples

Content type
application/json
{
  • "npm": "owner",
  • "npm-cli-bot": "developer"
}

Set user membership in an org

Set a user's membership in an org. If the user is not already a member, an invite will be sent.

Authorizations:
npmSessionToken
path Parameters
orgName
required
string

Name of an org

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)
Request Body schema: application/json
required
user
string

Username to grant membership to org

role
string
Enum: "developer" "admin" "owner"

Role to give user in org

Responses

Request samples

Content type
application/json
{
  • "user": "string",
  • "role": "developer"
}

Response samples

Content type
application/json
{
  • "org": {
    },
  • "user": "string",
  • "role": "string"
}

Remove user membership in an org

Remove a user's membership in an org

Authorizations:
npmSessionToken
path Parameters
orgName
required
string

Name of an org

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)
Request Body schema: application/json
required
user
string

Username to remove from the org

Responses

Request samples

Content type
application/json
{
  • "user": "string"
}

Response samples

Content type
application/json
{
  • "error": "Missing \"Bearer\" header."
}

Get teams in an org

Get all of the teams in an org

Authorizations:
npmSessionToken
path Parameters
orgName
required
string

Name of an org

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)

Responses

Response samples

Content type
application/json
[
  • "@npmcli:wombats"
]

Publish

Publish a new version of a package

Authorizations:
npmAccessTokennpmSessionTokengranularAccessTokenoidcIdToken
path Parameters
escapedPackageName
required
string
Example: @npmcli%2Farborist

The name of a package. Scoped packages need "/" to be url encoded to "%2F"

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)
Request Body schema: application/json
required
_id
string

The name and version of the package being published

name
string

The name of the package being published

description
string

The description of the package being published

object

dist-tag to apply for this new version

object
object

manifest (package.json) of the package to be published, indexed by the version being published

access
string
Enum: "public" "restricted"

Access level for this package. Whether it is public or not.

object

Tarball and provenance attestation attachments

Responses

Request samples

Content type
application/json
{
  • "_id": "npm@2.0.0",
  • "name": "npm",
  • "description": "a package manager for JavaScript",
  • "dist-tags": {
    },
  • "dist": {},
  • "versions": {
    },
  • "access": "public",
  • "_attachments": {
    }
}

Response samples

Content type
application/json
{
  • "success": true
}

Search

Search for packages on the registry

Search for packages on the registry

query Parameters
text
required
string

The search query text

size
number

The number of search results to return

from
number

The starting index of the search results

Responses

Response samples

Content type
application/json
{
  • "objects": [
    ],
  • "total": 1,
  • "time": "2026-03-24T07:35:20.725Z"
}

Stage

Fetch a list of all staged package versions for the authenticated user.

Retrieve staged package versions that are awaiting maintainer review.

This endpoint returns only items visible to the authenticated user. Results will be returned in the order of most recently staged first in a descending order. Results are paginated and can be filtered by package name using the package query parameter.

Requirements

  • User MUST be authenticated with a valid npm token
Authorizations:
npmAccessTokengranularAccessToken
query Parameters
package
string

Filter the entire list of staged package versions by package name, url-encoded.

page
integer
Default: 0

Page number for pagination (0-indexed)

perPage
integer <= 100
Default: 10

Number of items to return per page

header Parameters
Authorization
required
string^Bearer .+

Authentication header. Supports both Bearer authentication.

Formats:

  • Bearer <token> - npm access token or granular access token

Accepted token types:

  • npm access token (traditional user token)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": 0,
  • "perPage": 10,
  • "total": 2
}

Publishes a package version to staging to be reviewed by maintainers.

Submit a package version to staging for maintainer review.

The request body must contain a publish-style packument payload, including version metadata and package attachments. The staged item can then be reviewed, inspected, approved, or deleted by authorized maintainers.

Requirements

  • Package MUST exist or be creatable by the authenticated publisher
  • User MUST be authenticated with a valid npm token
  • Request body MUST include required fields in StagedPackumentRequest
Authorizations:
npmAccessTokengranularAccessToken
path Parameters
package-name
required
string

The name of the package to stage, including scope if applicable, url-encoded and slash-escaped.

header Parameters
Authorization
required
string^Bearer .+

Authentication header. Supports both Bearer authentication.

Formats:

  • Bearer <token> - npm access token or granular access token

Accepted token types:

  • npm access token (traditional user token)
Request Body schema: application/json
required
_id
string

The package name, including scope if applicable.

name
required
string

The name of the package, including scope if applicable.

description
string

A short description of the package.

version
string

The latest version string. Informational; the actual version to publish is determined by the first key in the versions object.

access
string
Enum: "public" "private"

The access level for the package. 'public' or 'private'.

required
object

An object where each key is a semver version string and the value is the version metadata. The registry assumes the FIRST key in this object is the newest version being published. Only include the single new version being published.

object

Mapping of distribution tags to semver version strings. e.g., {"latest": "1.2.3"}

readme
string

The README content for the package.

Array of objects

List of package maintainers.

author
string

The package author.

license
string

The SPDX license identifier.

object

The source code repository.

main
string

The entry point module.

object

Package scripts.

_nodeVersion
string

The version of node used to publish the package.

_npmVersion
string

The version of npm used to publish the package.

required
object

An object containing the binary attachments. Each key is an attachment name (typically {version}.tgz for the tarball). The first attachment with content_type: 'application/octet-stream' is treated as the tarball; if no content_type is set, the first attachment is used. An optional sigstore provenance bundle attachment may also be included.

_rev
string

Packument document revision. May be included when updating an existing package.

Responses

Request samples

Content type
application/json
{
  • "_id": "string",
  • "name": "string",
  • "description": "string",
  • "version": "string",
  • "access": "public",
  • "versions": {
    },
  • "dist-tags": {
    },
  • "readme": "string",
  • "maintainers": [
    ],
  • "author": "string",
  • "license": "string",
  • "repository": {
    },
  • "main": "string",
  • "scripts": {
    },
  • "_nodeVersion": "string",
  • "_npmVersion": "string",
  • "_attachments": {
    },
  • "_rev": "string"
}

Response samples

Content type
application/json
{
  • "message": "Package version staged successfully.",
  • "stageId": "f8e7a45b-7a5f-4f31-8e6d-9dd1c6ef38c0"
}

Get details about a specific staged package version.

Retrieve detailed metadata for a single staged package version.

Use this endpoint to inspect a staged item before taking action, including package identity, version, dist-tag, creator, and tarball information.

Requirements

  • stage-id MUST reference an existing staged package version
  • User MUST be authenticated with a valid npm token
Authorizations:
npmAccessTokengranularAccessToken
path Parameters
stage-id
required
string <uuid>

Unique identifier for the staged package version.

header Parameters
Authorization
required
string^Bearer .+

Authentication header. Supports both Bearer authentication.

Formats:

  • Bearer <token> - npm access token or granular access token

Accepted token types:

  • npm access token (traditional user token)

Responses

Response samples

Content type
application/json
{
  • "id": "1de6f3db-2ed9-4d72-b3dd-8f0e2b474a2f",
  • "packageName": "@npmcli/example-package",
  • "version": "1.2.3",
  • "tag": "latest",
  • "createdAt": "2026-03-16T09:00:00.000Z",
  • "actor": "octocat",
  • "actorType": "user",
  • "access": "public",
  • "shasum": "4f7f5f1d5bcf2f72f6e4d6c4f3b2812d8a2f6c19"
}

Delete a staged package version.

Remove a staged package version from review.

This endpoint permanently deletes the staging record identified by stage-id. Once deleted, the staged version can no longer be approved unless it is staged again.

Requirements

  • stage-id MUST reference an existing staged package version
  • User MUST be authenticated with a valid npm token
  • User MUST provide a valid npm-otp value for 2FA accounts
Authorizations:
npmAccessTokengranularAccessToken
path Parameters
stage-id
required
string <uuid>

Unique identifier for the staged package version.

header Parameters
Authorization
required
string^Bearer .+

Authentication header. Supports both Bearer authentication.

Formats:

  • Bearer <token> - npm access token or granular access token

Accepted token types:

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

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

When not provided for users with 2FA enabled, the API responds with 2FA polling payload.

Responses

Response samples

Content type
application/json
Example

When no Authorization header is provided or the token is invalid.

{
  • "message": "Unauthorized"
}

Approve a staged package version, publishing it to the npm registry.

Approve a staged package version and publish it to the npm registry.

This endpoint moves a version from staged review state to a published package version. On success, the staged record will be processed and the package version will become installable.

Requirements

  • stage-id MUST reference an existing staged package version
  • User MUST have permissions to approve and publish the package
  • User MUST be authenticated with a valid npm token
  • User MUST provide a valid npm-otp value for 2FA accounts
Authorizations:
npmAccessTokengranularAccessToken
path Parameters
stage-id
required
string <uuid>

Unique identifier for the staged package version.

header Parameters
Authorization
required
string^Bearer .+

Authentication header. Supports both Bearer authentication.

Formats:

  • Bearer <token> - npm access token or granular access token

Accepted token types:

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

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

When not provided for users with 2FA enabled, the API responds with 2FA polling payload.

Responses

Response samples

Content type
application/json
{
  • "message": "Package version approved and published successfully."
}

Get the tarball for a staged package version.

Download the package tarball for a staged package version.

This endpoint allows maintainers to inspect the contents of the staged package version by downloading the tarball directly from staging storage before approving it.

Requirements

  • stage-id MUST reference an existing staged package version
  • User MUST be authenticated with a valid npm token
Authorizations:
npmAccessTokengranularAccessToken
path Parameters
stage-id
required
string <uuid>

Unique identifier for the staged package version.

header Parameters
Authorization
required
string^Bearer .+

Authentication header. Supports both Bearer authentication.

Formats:

  • Bearer <token> - npm access token or granular access token

Accepted token types:

  • npm access token (traditional user token)

Responses

Response samples

Content type
application/octet-stream
(binary tarball data)

Team

Create a new team

Create a new team for an org

Authorizations:
npmSessionToken
path Parameters
orgName
required
string

Name of an org

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)
Request Body schema: application/json
required
name
string

The name of the team to create

description
string

The description of the team to create

Responses

Request samples

Content type
application/json
{
  • "name": "wombats",
  • "description": "All developers"
}

Response samples

Content type
application/json
{
  • "name": "wombats"
}

Delete a team

Delete a team from a given org

Authorizations:
npmSessionToken
path Parameters
orgName
required
string

Name of an org

teamName
required
string

Name of a team

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)

Responses

Response samples

Content type
application/json
{
  • "error": "Missing \"Bearer\" header."
}

Get all users in a team

Get all users in a team

Authorizations:
npmSessionToken
path Parameters
orgName
required
string

Name of an org

teamName
required
string

Name of a team

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)

Responses

Response samples

Content type
application/json
[
  • "npm",
  • "npm-cli-bot"
]

Add a user to a team

Add a user to a team in an org. The user must already be a member of the org.

Authorizations:
npmSessionToken
path Parameters
orgName
required
string

Name of an org

teamName
required
string

Name of a team

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)
Request Body schema: application/json
required
user
string

The username of the user to add to the team

Responses

Request samples

Content type
application/json
{
  • "user": "npm-cli-bot"
}

Response samples

Content type
application/json
{
  • "error": "Missing \"Bearer\" header."
}

Remove a user from a team

Authorizations:
npmSessionToken
path Parameters
orgName
required
string

Name of an org

teamName
required
string

Name of a team

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)
Request Body schema: application/json
required
user
string

The username of the user to remove from the team

Responses

Request samples

Content type
application/json
{
  • "user": "npm-cli-bot"
}

Response samples

Content type
application/json
{
  • "error": "Missing \"Bearer\" header."
}

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"
}

Trust

Trust-related endpoints for managing package trust and security settings.

Get all trusted publisher configurations for package

Retrieve all trusted publisher configurations for a package.

This endpoint allows users with write permission to the package to view all existing trusted publisher configurations that have been set up for OIDC token exchange for their package.

Configuration Structure

The structure of the payload follows a specific design. Each trusted provider has their own unique set of claims. In order to keep things clear and consistent, the properties to create a provider match the claims structure. The caveat is when a claim requires partial matching through parsing.

  • All configurations MUST include a type and claims object
  • Top-level "claims" MUST match the cloud provider's exact claim properties
  • Claims MAY use exact string matching when supported
  • Claims MAY use an object structure to define one or multiple partial matching rules
  • Partial matching properties MUST be defined and documented by this API specification
  • This documentation SHALL only provide matches for specifically defined claim items

Requirements

  • Package MUST exist
  • User MUST have write permission to the package
  • MUST have 2FA enabled on their account
  • User MUST be authenticated
Authorizations:
npmAccessTokengranularAccessToken
path Parameters
package
required
string

Name of the npm package, url-encoded

header Parameters
Authorization
required
string^Bearer .+

Authentication header. Supports both Bearer authentication.

Formats:

  • Bearer <token> - npm access token or granular access token

Accepted token types:

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

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

When not provided for users with 2FA enabled, the API responds with 2FA polling payload.

Responses

Response samples

Content type
application/json
Example
[ ]

Add trusted publisher configuration for package

Configure trusted publisher settings for a package to enable OIDC token exchange.

This endpoint allows users with write permission to the package to establish trust with CI/CD providers (GitHub Actions, GitLab CI, CircleCI, etc.) so that those services can publish to the package without requiring long-lived npm tokens.

Requirements

  • Package MUST exist
  • User MUST have write permission to the package
  • MUST have 2FA enabled on their account
  • User MUST be authenticated
Authorizations:
npmAccessTokengranularAccessToken
path Parameters
package
required
string

Name of the npm package, url-encoded

header Parameters
Authorization
required
string^Bearer .+

Authentication header. Supports both Bearer authentication.

Formats:

  • Bearer <token> - npm access token or granular access token

Accepted token types:

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

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

When not provided for users with 2FA enabled, the API responds with 2FA polling payload.

Request Body schema: application/json
required
Array
One of
type
required
string
Value: "github"

Type of the trusted publisher

required
object

Responses

Request samples

Content type
application/json
Example
[
  • {
    }
]

Response samples

Content type
application/json
Example
[
  • {
    }
]

Delete trusted publisher configuration

Delete a specific trusted publisher configuration for a package by its UUID.

This endpoint allows users with write permission to the package to remove an existing trusted publisher configuration that was previously set up for OIDC token exchange.

Requirements

  • Package MUST exist
  • User MUST have write permission to the package
  • MUST have 2FA enabled on their account
  • User MUST be authenticated
Authorizations:
npmAccessTokengranularAccessToken
path Parameters
package
required
string

Name of the npm package, url-encoded

config-uuid
required
string <uuid>

UUID of the trusted publisher configuration to delete

header Parameters
Authorization
required
string^Bearer .+

Authentication header. Supports both Bearer authentication.

Formats:

  • Bearer <token> - npm access token or granular access token

Accepted token types:

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

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

When not provided for users with 2FA enabled, the API responds with 2FA polling payload.

Responses

Response samples

Content type
application/json
{
  • "message": "Invalid trusted publisher config id format"
}