npm 14 🌐 Creating and Setting Up an npm Account - KandZ

⏱️ Estimated read: 10 min | |

An npm account is the credential that separates a consumer of packages from a publisher. Creating one takes minutes, but the account that can actually publish is a different thing from the account that was just created. Publishing to the public registry requires two gates to be cleared: email verification and two-factor authentication . The account exists after the signup form is submitted, but the CLI will reject a npm publish until both gates are satisfied. This chapter covers the signup process, the CLI login flow, the profile settings that control account metadata, and the 2FA configuration that makes the account publish-capable.

Key point: Publishing to npm requires either two-factor authentication enabled on the account or a granular access token with 2FA bypass enabled. An account without 2FA can log in and install packages, but it cannot publish .

Why account setup matters

The verification gate problem. The signup form creates the account record immediately, but the email address is unverified until the link in the verification email is clicked. npm blocks publishing until this happens . The account appears functional—npm login succeeds, npm whoami returns the username—but the first publish attempt fails with a verification error that is not always self-explanatory. Verifying the email before attempting any publish operation is the correct sequence.

The typo problem. The npm login command does not fail when the username is misspelled. It creates a new account with the misspelled name . A developer who types jane-doe instead of janedoe now has two accounts, and the packages published to the first are inaccessible from the second. Running npm whoami immediately after login confirms which account is active and catches the typo before it causes a split identity.

The publishing security problem. The npm registry requires 2FA for publishing because a compromised account can push malicious code to every project that depends on the packages it owns. The auth-and-writes mode requires an OTP for publishing, unpublishing, changing package access, and modifying account settings . The auth-only mode requires an OTP for login and authentication changes but not for publishing, which means an account with auth-only can still be used to publish if the password is compromised. For a publishing account, auth-and-writes is the correct mode.

The recovery problem. Recovery codes are generated during 2FA setup and are the only way back into an account when the 2FA device is lost . Using a recovery code triggers a 72-hour security hold during which the account can log in and change the password but cannot publish or create tokens . The hold is not a bug; it is a window for the legitimate owner to secure the account while limiting the damage a compromised recovery code can cause.

a. Creating the Account and Verifying Email

The signup form at npmjs.com/signup requires three fields. The username is displayed on every package published and on interactions with other users. It must be lowercase and may contain hyphens and numerals . The email address is added to package metadata and is visible to anyone who downloads the packages. The password must meet npm’s guidelines, which include length requirements and a check against the Have I Been Pwned database.

After submitting the form and accepting the End User License Agreement and Privacy Policy, npm sends a verification email. The account is created at this point, but publishing is blocked until the link is clicked . The verification is a single step, but it is the difference between an account that can install and an account that can publish.

b. Logging In and Confirming Identity

The npm login command authenticates the CLI against the registry and stores the credentials in the .npmrc file. It prompts for username, password, and email address. If 2FA is already enabled, it also prompts for a one-time password .

# Authenticate the CLI with the npm account
npm login
# Prompts: Username, Password, Email, and OTP if 2FA is enabled

# Confirm the active account
npm whoami
# Output: the npm username

The whoami check is the cheapest way to catch a login error. If the output does not match the intended username, the login created or used a different account, and publishing from this session will target the wrong identity .

c. Profile Settings and Two-Factor Authentication

Profile metadata such as full name and homepage is managed through npm profile set. The email address and avatar are changed through the website, not the CLI. Two-factor authentication is the setting that determines whether the account can publish.

The auth-and-writes mode requires an OTP for every action that auth-only requires, plus publishing, setting dist-tags, and changing package access . This is the mode required for a publishing account. The auth-only mode is insufficient because it leaves publishing unprotected by the second factor .

# Enable 2FA for publishing and account writes
npm profile enable-2fa auth-and-writes

# Confirm the 2FA mode
npm profile get two-factor-auth

Security-key configuration is done through the website, where biometric devices and physical keys can be registered. Recovery codes are generated during setup and must be stored outside the 2FA device . Linking a GitHub account provides a secondary recovery path if both the device and the recovery codes are lost .

Complete Example Session

# ============================================
# PART 1: CREATE THE ACCOUNT ON THE WEBSITE
# ============================================
# Navigate to https://www.npmjs.com/signup
# Username: lowercase, hyphens and numerals allowed
# Email: visible in package metadata
# Password: must meet npm password guidelines


# ============================================
# PART 2: VERIFY THE EMAIL ADDRESS
# ============================================
# Open the verification email
# Click the verification link
# Publishing is blocked until this step completes


# ============================================
# PART 3: LOG IN FROM THE CLI
# ============================================
npm login
# Enter username, password, email when prompted
# Enter OTP if 2FA is already enabled


# ============================================
# PART 4: CONFIRM THE ACTIVE ACCOUNT
# ============================================
npm whoami
# Should print the exact username from signup
# A mismatch means a typo created a new account


# ============================================
# PART 5: VIEW PROFILE SETTINGS
# ============================================
npm profile get
# Shows name, email verification status, 2FA mode


# ============================================
# PART 6: UPDATE PROFILE METADATA
# ============================================
npm profile set fullname "Jane Developer"
npm profile set homepage "https://example.com"


# ============================================
# PART 7: ENABLE 2FA FOR PUBLISHING
# ============================================
npm profile enable-2fa auth-and-writes
# Follow prompts to register a security key
# Save recovery codes outside the 2FA device


# ============================================
# PART 8: LINK GITHUB FOR RECOVERY
# ============================================
# Web: Account Settings → Linked Accounts → Link with GitHub
# Provides a recovery path if 2FA device is lost


# ============================================
# PART 9: CONFIRM 2FA MODE
# ============================================
npm profile get two-factor-auth
# Should show "auth-and-writes"


# ============================================
# PART 10: TEST WRITE AUTHENTICATION
# ============================================
npm token list
# Requires OTP if auth-and-writes is enabled
# Confirms the account can authenticate for writes

The ten parts cover the full path from signup to a publish-capable account. Parts 1 and 2 create and verify the account. Parts 3 and 4 confirm the CLI is authenticated as the correct identity. Parts 7 and 9 enable and confirm the 2FA mode that publishing requires.

Quick Reference

Account Setup Commands

Command	Purpose
`npm login`	Authenticate CLI, save credentials
`npm whoami`	Confirm active username
`npm profile get`	View profile settings
`npm profile set <key> <value>`	Update profile metadata
`npm profile enable-2fa auth-and-writes`	Enable 2FA for publishing
`npm profile enable-2fa auth-only`	Enable 2FA for login only

2FA Modes

Mode	Login	Publish	Package Access
`auth-only`	OTP	No OTP	No OTP
`auth-and-writes`	OTP	OTP	OTP

Profile Properties

Property	CLI Settable	Web Only
`fullname`	Yes	No
`homepage`	Yes	No
`email`	No	Yes
`avatar`	No	Yes
`github`	No	Yes

Best Practices

✅ Do This:

# Confirm identity immediately after login
npm whoami                                                              # ✅

# Enable auth-and-writes before attempting to publish
npm profile enable-2fa auth-and-writes                                  # ✅

# Store recovery codes in a password manager
# Not on the 2FA device itself                                          # ✅

# Link GitHub for secondary account recovery
# Web: Account Settings → Linked Accounts                               # ✅

# Verify email before any publish attempt
# Check inbox for verification link                                     # ✅

❌ Don’t Do This:

# Publish without 2FA or a bypass token
npm publish  # Fails without 2FA                                       # ❌

# Skip npm whoami after login
# Misspelled username creates a new account                             # ❌

# Use auth-only and expect to publish without OTP
npm profile enable-2fa auth-only                                       # ❌

# Keep recovery codes only on the 2FA device
# Loss of device means loss of recovery path                            # ❌

Common Pitfalls

Pitfall	Why It Happens	Fix
Publish fails with 2FA error	2FA not enabled or wrong mode	`npm profile enable-2fa auth-and-writes`
Login created wrong account	Username typo	`npm whoami` to verify; contact Support
Publishing blocked	Email not verified	Click verification link
Lost 2FA device, locked out	No recovery codes or GitHub link	Use recovery code; 72-hour hold applies
`npm profile` command fails	npm client older than 5.5.1	`npm install npm@latest -g`

Real-World Examples

1. Signup URL

https://www.npmjs.com/signup

2. Login and Verify Identity

npm login && npm whoami

3. View Profile

npm profile get

4. Set Full Name

npm profile set fullname "Jane Developer"

5. Enable 2FA for Publishing

npm profile enable-2fa auth-and-writes

6. Check 2FA Mode

npm profile get two-factor-auth

7. Change Password from CLI

npm profile set password

8. Link GitHub (Web)

Account Settings → Linked Accounts & Recovery → Link with GitHub

9. Test Write Authentication

npm token list

10. Recovery Code Storage

Store in password manager, not on the 2FA device

Visual

The Two Gates to Publishing

┌──────────────────────────────────────────────────────────────┐
│  SIGNUP FORM                                                 │
│                                                              │
│  ┌─────────────────┐                                         │
│  │ Username        │                                         │
│  │ Email           │                                         │
│  │ Password        │                                         │
│  └────────┬────────┘                                         │
│           ▼                                                  │
│  ┌─────────────────┐                                         │
│  │ Account created │  Can log in, install packages           │
│  └────────┬────────┘                                         │
│           ▼                                                  │
│  ┌─────────────────┐                                         │
│  │ GATE 1:         │────► NO: publish blocked                │
│  │ Email verified? │                                         │
│  └────────┬────────┘                                         │
│           │ YES                                              │
│           ▼                                                  │
│  ┌─────────────────┐                                         │
│  │ GATE 2:         │────► NO: publish blocked                │
│  │ 2FA enabled?    │      (or bypass token)                  │
│  └────────┬────────┘                                         │
│           │ YES                                              │
│           ▼                                                  │
│  ┌─────────────────┐                                         │
│  │ Ready to        │                                         │
│  │ publish         │                                         │
│  └─────────────────┘                                         │
│                                                              │
│  Both gates must be cleared. Neither is optional.            │
│                                                              │
└──────────────────────────────────────────────────────────────┘

2FA Mode Comparison

┌──────────────────────────────────────────────────────────────┐
│  ACTION                    auth-only    auth-and-writes       │
│                                                              │
│  npm login                 OTP           OTP                  │
│  npm profile set           OTP           OTP                  │
│  npm token create          OTP           OTP                  │
│  npm publish               NO OTP        OTP                  │
│  npm unpublish             NO OTP        OTP                  │
│  npm access grant          NO OTP        OTP                  │
│                                                              │
│  auth-and-writes is required for publishing.                 │
│  auth-only leaves publish unprotected by 2FA.                │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Recovery Paths

┌──────────────────────────────────────────────────────────────┐
│  2FA ENABLED                                                 │
│                                                              │
│  ┌─────────────────┐                                        │
│  │ Security key    │  Primary authentication                │
│  └────────┬────────┘                                        │
│           │ LOST                                             │
│           ▼                                                  │
│  ┌─────────────────┐                                        │
│  │ Recovery codes  │  One-time use, stored offline          │
│  └────────┬────────┘                                        │
│           │ LOST                                             │
│           ▼                                                  │
│  ┌─────────────────┐                                        │
│  │ Linked GitHub   │  Secondary recovery for Support        │
│  └────────┬────────┘                                        │
│           │ LOST                                             │
│           ▼                                                  │
│  ┌─────────────────┐                                        │
│  │ npm Support     │  Manual verification required          │
│  └─────────────────┘                                        │
│                                                              │
│  Recovery code login triggers a 72-hour security hold.       │
│  During the hold: can log in, cannot publish.                │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Summary

Item	Value
Signup URL	`https://www.npmjs.com/signup`
Username rules	Lowercase, hyphens, numerals
Email verification	Required before publishing
CLI login	`npm login`
Identity check	`npm whoami`
2FA for publishing	`auth-and-writes` mode
Publishing requirement	2FA or granular bypass token
Recovery code hold	72 hours, no publishing
npm version for profile	5.5.1 or higher

Key takeaways:

Email verification is a publishing gate, not a formality. The account exists after signup, but npm publish fails until the verification link is clicked . Verify before attempting any publish operation.
npm whoami catches username typos. A misspelled username during npm login creates a new account rather than failing . Checking the identity immediately after login prevents publishing under the wrong account.
auth-and-writes is the mode publishing requires. auth-only covers login and authentication changes but not publishing. An account with auth-only can log in but cannot publish without an OTP prompt that never arrives .
Recovery codes are the path back into a locked account. Using one triggers a 72-hour security hold during which the account can log in and change the password but cannot publish . Store the codes outside the 2FA device.
The CLI profile commands require npm 5.5.1 or higher. Older clients cannot change account settings from the command line. Updating npm is the first step when npm profile commands fail .

Remember: An npm account is a two-stage credential. The first stage is an identity that can install packages and read the registry. The second stage—email verified and 2FA enabled—is an identity that can publish. The gap between the two is where most first-publish attempts fail. Complete both stages before writing the first npm publish command, confirm the active account with npm whoami, and store the recovery codes somewhere the 2FA device cannot reach. The account that can publish is the account that can affect every project depending on the packages it owns; the setup steps exist to make that power deliberate rather than accidental.

Was this helpful?

Stop using slow, ad-bloated tool sites! 🤮

🔎 Search “KandZ Tools” on Google to use many professional utilities for free.

KandZ.me is the ultimate minimalist hub for:
✅ Finance (Mortgage, Interest, Inflation)
✅ Tech (Base64, JSON, Dev Suite, IP)
✅ Health (BMI, BMR, TDEE)
✅ Productivity (Timer, Workspace, QR)

⚡️ Fast & Private
🔒 No data leaves your device
💎 100% Free

🔗 Use it now: https://tools.kandz.me
🔖 Bookmark it—you’ll need it later!