pnpm install fails with 401/403 when registry token is expired or read-only

Direct Answer

When pnpm install or pnpm publish returns an HTTP 401 Unauthorized or 403 Forbidden, the problem almost always lies in the credentials that pnpm sends to the registry. pnpm itself does not distinguish between an expired token, a revoked token, or a token that lacks the necessary scope – it simply forwards the token stored in .npmrc or supplied via an environment variable. The only way to tell whether the failure is due to expiration, insufficient permissions, or a transient registry outage is to look at the full response body that the registry returns.

Likely Explanation

• Expired or revoked token: The registry rejects the token and typically includes a message such as "token expired" or "Bad credentials" in the JSON body.
• Insufficient scope (e.g., read‑only token used for publish): The registry accepts the token but denies the operation, often returning a 403 with a body that says "permission denied" or "you do not have permission to perform this action".
• Network or registry outage: The registry may return a generic 5xx status or a 4xx with no clear message. In this case the body usually contains nothing useful for credential diagnosis.

Confirmed Facts (from pnpm and registry behavior)

• pnpm stores npm‑compatible tokens in .npmrc using the format //registry.example.com/:_authToken=YOUR_TOKEN.
• pnpm does not enforce token expiration; it simply forwards whatever is present.
• Registry‑specific error payloads are the only reliable source for determining the exact cause of a 401/403.
• pnpm versions 7 and later expose the full HTTP response when run with --verbose, which can be used to capture the body.

Minimal Diagnostic Steps

1. Confirm the token is present in the configuration:

   pnpm config get //registry.example.com/:_authToken
   

   If the output is empty, the token is missing and you need to add it to .npmrc or set the PNPM_AUTH_TOKEN environment variable.
2. Test the token directly against the registry API:

   curl -H "Authorization: Bearer $(pnpm config get //registry.example.com/:_authToken)" \
     https://registry.example.com/-/v1/package/your-package
   

   Inspect the JSON body of the response. A message like "token expired" or "Bad credentials" indicates expiration; a message about missing permissions indicates a scope issue.
3. Run pnpm with verbose output to capture the body:

   pnpm install --verbose
   

   Look for the error or message fields in the logged response.
4. If the token is expired or revoked, generate a new one in the registry UI and update .npmrc or the CI secret.

Configuring Token Lifecycles

• Treat all tokens as registry‑managed secrets. Do not hard‑code them in source control.
• For CI/CD pipelines, store the token in the secret store and inject it via an environment variable (e.g., PNPM_AUTH_TOKEN).
• Choose a rotation strategy that matches your team’s security policy. Some teams prefer short‑lived tokens (e.g., 24 h) and regenerate them automatically; others use long‑lived tokens but rotate them monthly.
• When a registry supports token scopes, request the minimal scope required for the operation (e.g., read:packages for installs, write:packages for publishes).

What We Still Need to Know

To give a more precise recommendation, could you share the exact body that the registry returned with the 401/403? If the body is empty or generic, the issue may be a transient network problem rather than a credential problem.