unpkg/docs/api.md

Authentication

Some API methods require an authentication token. This token is a JSON web token that contains a list of "scopes" (i.e. permissions).

Once you obtain an API token (see below) you simply include it in the Authorization header of your request as a base-64 encoded string, i.e.

Authorization: base64(token)

GET /api/publicKey

The public key unpkg uses to encrypt authentication tokens, as JSON. You can also find the key as plain text on GitHub.

This can be useful to verify a token was issued by unpkg.

Required scope: none

Query parameters: none

Example:

> curl "https://unpkg.com/api/publicKey"
{
  "publicKey": "..."
}

POST /api/auth

Creates and returns a new auth token. By default, auth tokens have the following scopes:

{
  "blacklist": {
    "read": true
  }
}

Required scope: none

Body parameters: none

Example:

> curl -X POST "https://unpkg.com/api/auth"
{
  "token": "..."
}

Please reach out to @mjackson if you need a token with additional scopes.

GET /api/auth

Verifies and returns the payload contained in the given auth token.

Required scope: none

Query parameters: none

Example:

> curl -H "Authorization: $BASE_64_ENCODED_TOKEN" "https://unpkg.com/api/auth"
{
  "jti": "...",
  "iss": "https://unpkg.com",
  "iat": ...,
  "scopes": { ... }
}

Blacklist

To protect unpkg users and prevent abuse, unpkg manages a blacklist of npm packages that are known to contain harmful code.

GET /api/blacklist

Returns a list of all packages that are currently blacklisted.

Required scope: blacklist.read

Query parameters: none

Example:

> curl -H "Authorization: $BASE_64_ENCODED_TOKEN" "https://unpkg.com/api/blacklist"
{
  "blacklist": [ ... ]
}

POST /api/blacklist

Adds a package to the blacklist.

Required scope: blacklist.add

Body parameters:

• packageName - The package to add to the blacklist (required)

Example:

> curl -H "Authorization: $BASE_64_ENCODED_TOKEN" -d '{"packageName":"bad-package"}' "https://unpkg.com/api/blacklist"
{
  "ok": true
}

DELETE /api/blacklist

Removes a package from the blacklist.

Required scope: blacklist.remove

Body parameters:

• packageName - The package to remove from the blacklist (required)

Example:

> curl -X DELETE -H "Authorization: $BASE_64_ENCODED_TOKEN" -d '{"packageName":"bad-package"}' "https://unpkg.com/api/blacklist"
{
  "ok": true
}

Stats

GET /api/stats

TODO