npm registry

Publish and install private packages.

What it is

A private npm registry for your organization, served by the platform and spoken to with the ordinary npm client. Find it under npm in the console: the page gives you the registry URL, the exact .npmrc lines to paste, every package published and the permissions you hold.

There is nothing to create. The registry exists from the moment your organization does, and a scope such as @acme is only the start of a package name: it exists once something is published under it. A package appears on its first npm publish.

Publishing and installing need credentials, except for a package you have made public.

Concepts

Term Meaning
Registry One per organization, created with it, addressed as https://npm.<domain>/<organization>/; the npm page shows the exact URL.
Package A published name, scoped (@acme/utils) or unscoped (utils), with all of its versions.
Version One published release. Its bytes are fixed at publish time and never change.
Packument The metadata document npm reads for a package: every version's manifest, its dist-tags and its tarball URL.
Dist-tag A moving name for a version. latest unless you publish with --tag.
npm token A short-lived credential created in the console and used as _authToken. Shown once.
Access key A Deutsche Cloud access key, usable verbatim as _authToken. Revocable one at a time, so this is the credential for CI.
Integrity The sha512- digest of a version's tarball. npm verifies it on every download.

How to

Connect the npm client

Open npm in the console. Connect the npm CLI walks through it: use Create token (the token appears once and is filled into the snippet), optionally type a scope, and copy the .npmrc lines into ~/.npmrc or into an .npmrc beside your package.json:

registry=https://npm.<domain>/<organization>/
//npm.<domain>/<organization>/:_authToken=<token>

To send only one scope here and leave everything else on npmjs.org, replace the first line:

@acme:registry=https://npm.<domain>/<organization>/
//npm.<domain>/<organization>/:_authToken=<token>

Confirm the credential with npm whoami --registry https://npm.<domain>/<organization>/; it prints the IAM user the token belongs to.

Publish a package

Publishing is the one step that only the npm CLI does: it packs the directory it runs in and uploads it. The console has no upload. Run this in the package directory, with the registry configured as above:

npm publish

Scoped and unscoped names both work. Pin the registry in the package itself instead of in .npmrc with:

{ "publishConfig": { "registry": "https://npm.<domain>/<organization>/" } }

Bump the version before every publish. A version that already exists is refused, and the bytes behind it stay as they were.

Install a package

npm install @acme/utils

The registry serves the packument, the dist-tags and the tarball. npm checks the tarball against the sha512 integrity recorded at publish time and fails the install on a mismatch.

Publish from CI

Create a Deutsche Cloud access key and use <access key id>:<secret> as the _authToken value. It carries that IAM user's permissions and does not expire after 12 hours like a console token.

A console token (npm registry → Create token, or POST /npm/api/token) lasts 12 hours. Your live ones are listed under the button, by when they were made, each with Revoke; a revoked token is refused at once. The same holds for container registry login tokens (Push commands, GET/DELETE /ecr/api/login-tokens).

//npm.<domain>/<organization>/:_authToken=${EWS_ACCESS_KEY}
//npm.<domain>/<organization>/:always-auth=true

Browse what is published

npm lists every package with its latest version, version count and size. Open one to see all versions with the dist-tag pointing at each, who published it and when.

Manage dist-tags

Open the package, then Dist-tags. Move a tag with its version picker, remove one with the bin (not latest), or add one (next, beta) with Add a tag. This is npm dist-tag add without the terminal.

Change the description or make a package public

Open the package, then Settings. The description is shown in the package list. The next npm publish replaces it with the one in package.json.

Make public lets anyone install every version of that one package with no credentials. You type the package name to confirm. Publishing it still needs npm:PublishPackage, and Make private reverses it.

Unpublish a version

Open the package and use Unpublish version in the version's row menu. Anything with that version in a lockfile fails its next install.

Delete a package

Open the package, then Danger zone → Delete package, or use the row menu on the npm page. This removes the package and every version of it.

Give someone access

Access is IAM. The Permissions card on the npm page lists the npm actions and ticks the ones you hold. Attach NpmFullAccess to publish and manage, or NpmReadOnlyAccess to browse, to a user or a group under IAM. NpmReadOnlyAccess does not include npm:GetPackage, because downloading a tarball hands over source code, so add it where installs are needed. A custom policy can narrow any npm action to one package (rn:ews::<org id>:npm:package/<package id>).

Reference

Registry endpoints

The npm client talks to these directly; you do not call them by hand.

Request What
GET /-/ping liveness; needs no credential
GET /-/whoami the IAM user behind the token
GET /<package> the packument: versions, dist-tags, publish times
PUT /<package> a publish
GET /<package>/-/<name>-<version>.tgz the tarball; the ETag is the version's integrity hash

A scoped name is URL-encoded in the path (%40acme%2Futils). The tarball filename drops the scope: @acme/utils@1.2.3 is served from /@acme/utils/-/utils-1.2.3.tgz.

.npmrc lines

Line Effect
registry=<registry url>/ every package resolves here
@scope:registry=<registry url>/ only that scope resolves here
//<host>/<path>/:_authToken=<value> the credential; npm matches it by URL prefix, so the org path must be there
//<host>/<path>/:always-auth=true send the credential on tarball downloads too

Credentials

Credential Where it comes from Lifetime Revocation
npm token npm → Create token 12 hours expires on its own
Access key IAM → Access keys until revoked revoked individually

Both carry the full permissions of the IAM user behind them: anyone holding one publishes and installs as that user.

Package names and versions

Field Accepted
Name lowercase letters, digits, . _ -, optionally prefixed @scope/; 214 characters at most
Version semver major.minor.patch, with prerelease and build suffixes
Tag starts with a letter, then letters, digits, . _ -

Storage and billing

Every published version is stored as an object in your organization's storage and metered on your bill. Deleting a package releases that storage.

API

Operation Permission
GET /npm/api/packages npm:ListPackages
GET /npm/api/packages/{id} npm:DescribePackages
PATCH /npm/api/packages/{id} (description, visibility private or public) npm:PublishPackage
DELETE /npm/api/packages/{id} npm:DeletePackage
DELETE /npm/api/packages/{id}/versions/{version} npm:DeletePackage
PUT /npm/api/packages/{id}/dist-tags/{tag} (body { "version" }) npm:ManageDistTags
DELETE /npm/api/packages/{id}/dist-tags/{tag} npm:ManageDistTags
POST /npm/api/token (a 12-hour token) npm:GetAuthorizationToken

Lifecycle: old prereleases

Every organization has a lifecycle default for package versions. The platform's default expires only prereleases (1.2.0-beta.1) that nobody downloaded for 90 days. These are always kept:

  • released versions;
  • any version a dist-tag (latest, next, …) points at;
  • the newest 10 versions;
  • the latest release of every major.

An expired version disappears from npm view and npm install, but can be brought back for 7 days (POST /npm/api/packages/{id}/expired-versions/restore); after that it is unpublished. Downloads are recorded per version, so "not downloaded" counts from when that tracking began.

Organizations created after 2026-11-17 get the default active. Older ones see it as a preview — POST /npm/api/lifecycle-defaults/preview says what it would expire — until they enable it with PUT /npm/api/lifecycle-defaults (npm:PutLifecyclePolicy). The same rule format as the container registry lifecycle policies.

What is not supported

  • Deprecation messages on a package or a version.
  • Anonymous reads of private packages. Only a package switched to public under Settings installs without a credential.
  • Creating a package, registry or scope from the console. A package comes into being with its first npm publish.
  • Proxying npmjs.org. A package that is not published here is not resolved here — scope the registry line, or leave registry= pointing at npmjs.org and set only @scope:registry.
  • Revoking one npm token. Wait for the 12 hours, or use an access key where you need to revoke.

Troubleshooting

Symptom Cause Fix
E401 on publish or install no _authToken line matching that registry path, or the token expired copy the .npmrc lines from the npm page again; the auth line must carry the /<organization>/ path
E403 cannot publish over existing version that version is already published bump the version in package.json
E404 on install the registry line does not cover that package's scope add @scope:registry=<registry url>/, or set registry= to the platform registry
npm whoami names someone else an .npmrc in a parent directory, or ~/.npmrc, wins over the one you edited edit the file npm actually reads, or pass --registry and keep the token in the project .npmrc
an install fails on an integrity mismatch the cached tarball differs from the published one npm cache clean --force, then install again
Did this page help you?