Skip to content
privatenpmREGISTRY
Start free trial
Menu

Automate npm download keys after a sale

After a verified purchase, your server can issue a read-only download key for the bought package and send it to the customer.

Decide what a purchase grants

Your checkout and customer database own the sale. The registry provides read-only download keys (pdk_…) rather than a built-in license or billing record. Map each product or price in your store to one registry and the exact package IDs it grants there. Keep your order ID as the key's external_ref.

Download key form showing recipient, key name, and external reference fields
Record the buyer and your order reference when issuing a key.

Handle the payment event on your server

  1. Receive a paid or fulfilled event from Stripe or your other payment provider. Verify its signature using that provider's instructions, confirm the order and payment state, and record the provider event ID so retries cannot fulfill the order twice.
  2. Create or retrieve one organization API key for your fulfillment service under Settings → API keys. It needs permission to manage download keys; API access starts on Growth. Keep the gsk_… secret on your server.
  3. Call RegistryDownloadKeyService/IssueDownloadKey with the registry ID, recipient label, your order reference, and package IDs. Store the returned key ID and reveal-once secret securely. A retry must consult your saved order-to-key mapping before issuing another key.
  4. Email the customer the secret and .npmrc instructions from your own email service. Track send status so a mail failure can be retried without minting another key.
Selected packages access rule on the download key form
For a purchase, select only the packages included in that order.

The management request uses the Connect JSON endpoint on your app origin:

POST /privatenpmcom.core.registryaccess.v1.RegistryDownloadKeyService/IssueDownloadKey
Authorization: Bearer gsk_...
X-Idempotency-Key: order_1234
Content-Type: application/json

{"registryId":"reg_...","name":"Order 1234","recipient":"[email protected]","externalRef":"order_1234","packageIds":["rpkg_..."]}

Send the customer their install details

Use your existing transactional email service after saving the key and order mapping. Send to the verified order email address. This example assumes a package on the shared registry; substitute your custom domain and package name when appropriate:

Subject: Your Acme SDK download key

Your download key: pdk_...

Set ACME_NPM_TOKEN to that key, then add to .npmrc:
@acme:registry=https://registry.privatenpm.com/
//registry.privatenpm.com/:_authToken=${ACME_NPM_TOKEN}

Run: npm install @acme/sdk

The response's secret is shown only at issuance. Use the key ID to change access or revoke it later. A purchase cancellation or refund should trigger your own policy to revoke the key through the management API. Registry outgoing webhooks report registry changes; they do not receive Stripe payment events.

READY WHEN YOU ARE

Put private packages to work.

Start 30-day trial