Add API docs

docs/api.md

@@ -0,0 +1,131 @@
+# Authentication
+
+Some API methods require an authentication token. This token is a [JSON web token](https://en.wikipedia.org/wiki/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:
+
+```json
+{
+  "blacklist": {
+    "read": true
+  }
+}
+```
+
+Required scope: none
+
+Body parameters: none
+
+Example:
+
+```log
+> 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:
+
+```log
+> curl "https://unpkg.com/_auth?token=$TOKEN"
+{
+  "jti": "...",
+  "iss": "https://unpkg.com",
+  "iat": ...,
+  "scopes": { ... }
+}
+```
+
+### GET /\_publicKey
+
+The [public key](https://en.wikipedia.org/wiki/Public-key_cryptography) unpkg uses to encrypt authentication tokens, in plain text. You can also find the key [on GitHub](https://github.com/unpkg/unpkg/blob/master/public.key).
+
+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:
+
+```log
+> 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:
+
+```log
+> 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:
+
+```log
+> curl -X DELETE https://unpkg.com/_blacklist/bad-package -d '{"token": "$TOKEN"}'
+{
+  "ok": true
+}
+```
+
+# Stats
+
+### GET /\_stats
+
+TODO