npm.md

npm registry docs

The npm registry (api) isn’t documented very well. You can find some docs in npm/registry, but most of it can be best perused by reading code, such as libnpmaccess.

…or read this document.

Table of Contents

• Authentication
• Org
  • List teams in an org
  • List packages in an org
  • List users in an org
  • Add or change a user in an org
  • Remove a user from an org
• Team
  • Add or change a team
  • List users in a team
  • Add a user to a team
  • Remove a user from a team
  • List packages in a team
  • Add or change a package in a team
  • Remove a package from a team
• Packages
  • Get a package
  • Get collaborators of a package
  • Set maintainers for a package
  • Set 2fa access of a package
• Users
  • Get the current user (from the token)
  • Get a user
  • List packages for a user

Authentication

First, make sure to set npm to use 2fa for auth-only. Proper 2fa doesn’t work well as you’d have to fill in OTPs all the time.

npm profile enable-2fa auth-only

Then, create an npm token:

npm token create

Store that somewhere in a dotenv.

Org

List teams in an org

org=remarkjs

curl "https://registry.npmjs.org/-/org/$org/team" \
  -H "Authorization: Bearer $token"
# ["remarkjs:developers","remarkjs:foo"]

List packages in an org

org=remarkjs

curl "https://registry.npmjs.org/-/org/$org/package"
# {"remark":"write",…"remark-external-links":"write"}

List users in an org

Only users the token can see are shown.

org=remarkjs

curl "https://registry.npmjs.org/-/org/$org/user" \
  -H "Authorization: Bearer $token"
# {"wooorm":"owner",…"murderlon":"admin"}

Add or change a user in an org

org=remarkjs
user="wooorm"
role="owner" # "developer", "owner", or "admin"
# See https://docs.npmjs.com/org-roles-and-permissions.

curl "https://registry.npmjs.org/-/org/$org/user" \
  -X PUT \
  -H "Authorization: Bearer $token" \
  -H "Content-Type: application/json" \
  -d "{\"user\": \"$user\", \"role\": \"$role\"}"
# {"org":{"name":"remarkjs","size":5},"user":"wooorm","role":"owner"}

Remove a user from an org

org=remarkjs
user="wooorm"

curl "https://registry.npmjs.org/-/org/$org/user" \
  -X DELETE \
  -H "Authorization: Bearer $token" \
  -H "Content-Type: application/json" \
  -d "{\"user\": \"$user\"}"

Team

Add or change a team

org=remarkjs
team=bar
description=bravo

curl "https://registry.npmjs.org/-/org/$org/team" \
  -X PUT \
  -H "Authorization: Bearer $token" \
  -H "Content-Type: application/json" \
  -d "{\"name\": \"$team\",\"description\": \"$description\"}"
# {"name":"bar"}

List users in a team

org=remarkjs
team=developers

curl "https://registry.npmjs.org/-/team/$org/$team/user" \
  -H "Authorization: Bearer $token"
# ["wooorm",…]

Add a user to a team

org=remarkjs
team=foo
user=wooorm

curl "https://registry.npmjs.org/-/team/$org/$team/user" \
  -X PUT \
  -H "Authorization: Bearer $token" \
  -H "Content-Type: application/json" \
  -d "{\"user\":\"$user\"}"
# {}

Remove a user from a team

org=remarkjs
team=foo
user=johno

curl "https://registry.npmjs.org/-/team/$org/$team/user" \
  -X DELETE \
  -H "Authorization: Bearer $token" \
  -H "Content-Type: application/json" \
  -d "{\"user\":\"$user\"}"
# empty

List packages in a team

org=remarkjs
team=developers

curl "https://registry.npmjs.org/-/team/$org/$team/package" \
  -H "Authorization: Bearer $token"
# {"remark":"write",…"remark-external-links":"write"}

Add or change a package in a team

org=remarkjs
team=foo
package=remark-parse
permissions="read-write" # "read-only" or "read-write"

curl "https://registry.npmjs.org/-/team/$org/$team/package" \
  -X PUT \
  -H "Authorization: Bearer $token" \
  -H "Content-Type: application/json" \
  -d "{\"package\": \"$package\", \"permissions\": \"$permissions\"}"
# {}

Remove a package from a team

org=remarkjs
team=foo
package=remark-parse

curl "https://registry.npmjs.org/-/team/$org/$team/package" \
  -X DELETE \
  -H "Authorization: Bearer $token" \
  -H "Content-Type: application/json" \
  -d "{\"package\": \"$package\"}"
# empty response

Packages

Get a package

package=remark-parse # Use "@foo%2bar" for scoped packages

curl "https://registry.npmjs.org/$package" \
  -H "Accept: application/vnd.npm.install-v1+json" # Remove for full metadata.
# {"_id":"remark-parse","_rev":"35-c4b211558296c2be5fad20fd0a7b3b25","name":"remark-parse","maintainers":[…],…}

This can be used to find maintainers.

Get collaborators of a package

package=remark-parse

curl "https://registry.npmjs.org/-/package/$package/collaborators" \
  -H "Authorization: Bearer $token"
# {"wooorm":"write",…}

Set maintainers for a package

package=remark-parse
rev=10-4193cf2ba92283e3e8fd605d75108054

curl "https://registry.npmjs.org/$package/-rev/$rev" \
  -X PUT \
  -H "Authorization: Bearer $token" \
  -H "Content-Type: application/json" \
  -d "{
    \"_id\": \"$package\",
    \"_rev\": \"$rev\",
    \"maintainers\": [
      {\"email\":\"[email protected]\",\"name\":\"vweevers\"},
      {\"email\":\"[email protected]\",\"name\":\"wooorm\"}
    ]
  }" \
  --verbose

Set 2fa access of a package

package=remark-parse
tfa=true # true or false

curl "https://registry.npmjs.org/-/package/$package/access" \
  -X POST \
  -H "Authorization: Bearer $token" \
  -H "Content-Type: application/json" \
  -d "{\"publish_requires_tfa\": $tfa}"
# empty

Users

Get the current user (from the token)

curl "https://registry.npmjs.org/-/npm/v1/user" \
  -H "Authorization: Bearer $token"
# {"tfa":{"pending":false,…"fullname":"Titus Wormer",…"twitter":"wooorm","github":"wooorm"}

Get a user

user=wooorm

curl "https://registry.npmjs.org/-/user/org.couchdb.user:$user"
# {"_id":"org.couchdb.user:wooorm","email":"[email protected]","name":"wooorm"}

List packages for a user

user=wooorm

curl "https://registry.npmjs.org/-/user/$user/package"
# {"retext-latin":"write",…"remark-bookmarks":"write"}