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 publishScoped 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/utilsThe 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=trueBrowse 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 |