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 can pass it to the server in one of two ways:

• For GET/HEAD requests, use the ?token query parameter
• For all other requests, use the {token} parameter as part of the JSON in the request body

POST /_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/_auth"
{
  "token": "eyJhbGciOiJS..."
}

GET /_auth

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

Required scope: none

Query parameters:

• token - The auth token to verify and decode

Example:

> curl "https://unpkg.com/_auth?token=$TOKEN"
{
  "jti": "...",
  "iss": "https://unpkg.com",
  "iat": ...,
  "scopes": { ... }
}

GET /_publicKey

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

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

Required scope: none

Query parameters: none

Blacklist

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

GET /_blacklist

Returns a list of all packages that are currently blacklisted.

Required scope: blacklist.read

Query parameters: none

Example:

> curl "https://unpkg.com/_blacklist?token=$TOKEN"
{
  "blacklist": [ ... ]
}

POST /_blacklist

Adds a package to the blacklist.

Required scope: blacklist.add

Body parameters:

• token - The auth token
• packageName - The package to add to the blacklist

Example:

> curl https://unpkg.com/_blacklist -d '{"token": "$TOKEN", "packageName": "bad-package"}'
{
  "ok": true
}

DELETE /_blacklist/:packageName

Removes a package from the blacklist.

Required scope: blacklist.remove

Body parameters:

• token - The auth token

Example:

> curl -X DELETE https://unpkg.com/_blacklist/bad-package -d '{"token": "$TOKEN"}'
{
  "ok": true
}

Stats

GET /_stats

TODO