Authentication

Every call is made as an account: the one whose API key it sends. A key sees exactly what its account sees, and only the sources that account's plan opens.

Send your key

Send the key in the Authorization header of every call, as a bearer token: Authorization: Bearer bk_…. Keys are never read from the address, so they do not end up in logs.

GET /api/v1/me

cURL

curl --request GET \
  --url 'https://carryspec.com/api/v1/me' \
  --header "Authorization: Bearer $CARRYSPEC_API_KEY"

JavaScript

const response = await fetch("https://carryspec.com/api/v1/me", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CARRYSPEC_API_KEY}`,
  },
});
if (!response.ok) {
  throw new Error(`${response.status}: ${await response.text()}`);
}
console.log(JSON.stringify(await response.json(), null, 2));

Python

import json
import os
import urllib.error
import urllib.request

request = urllib.request.Request(
    "https://carryspec.com/api/v1/me",
    method="GET",
    headers={
        "Authorization": "Bearer " + os.environ["CARRYSPEC_API_KEY"],
    },
)
try:
    with urllib.request.urlopen(request) as response:
        print(json.dumps(json.load(response), indent=2))
except urllib.error.HTTPError as error:
    print(error.code, error.read().decode())

note

A browser that is logged in on the site is recognised too, which is how Swagger works for you without a key. Only calls made with a key count against your plan's calls a day.

Calls that need no key

These answer anyone:

• GET /api/v1/event-types: list the kinds of event.
• GET /api/health: check the service is up.

Making and revoking keys

• Make a key on the API page of your account. It needs a name, so you can tell later which program uses it.
• The key is shown once. Only a hash of it is kept, so it cannot be shown again: if it is lost, make another and revoke the old one.
• An account can have 5 working keys at once.
• Revoking a key on the same page stops it at once.

When a key is refused

A refusal carries the header WWW-Authenticate: Bearer and an error whose code says why:

Status	code	When
401	not_signed_in	No key was sent.
401	bad_key	The key is wrong, revoked, or its account is blocked.
403	account_blocked	The account was blocked.

Keeping keys safe

• Keep keys on a server, in an environment variable such as CARRYSPEC_API_KEY, which every example in these docs reads.
• Use one key per program, so one can be revoked without stopping the rest.

warning

Never put a key in a web page, a mobile app or a public repository: anyone who finds it can use your account's calls.