Authentication with an API key

Every request to the Checkslip API needs your API key. Create keys on the API keys page of the web app.

Send the API key#

Put the key in the Authorization header as a Bearer token on every request. Checkslip keys start with csk_ and go over HTTPS only.

Authorization: Bearer csk_…

curl https://api.checkslip.com/api/slips/lookup \
  -H "Authorization: Bearer $CHECKSLIP_API_KEY" \
  -H "Idempotency-Key: order-1042-slip-1" \
  -H "Content-Type: application/json" \
  -d '{"qr":"00330006000001010306902126302105340875102TH9104F86F"}'

const res = await fetch("https://api.checkslip.com/api/slips/lookup", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CHECKSLIP_API_KEY}`,
    "Idempotency-Key": "order-1042-slip-1",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    qr: "00330006000001010306902126302105340875102TH9104F86F",
  }),
});
const data = await res.json();

import os

import requests

res = requests.post(
    "https://api.checkslip.com/api/slips/lookup",
    headers={
        "Authorization": f"Bearer {os.environ['CHECKSLIP_API_KEY']}",
        "Idempotency-Key": "order-1042-slip-1",
    },
    json={
        "qr": "00330006000001010306902126302105340875102TH9104F86F",
    },
)
data = res.json()

What a key may do#

When you create a key you choose what it may do. Give each key only the scopes your system uses.

• Each scope stands alone; none includes another. For example, slip:lookup does not give slip:read.
• A key's scopes cannot be changed after it is created. For other scopes, create a new key.

Keep keys safe#

• The web app shows the whole key once, when you create it. Copy it right away; if you lose it, create a new key.
• Keep keys on your server, for example in environment variables or a secrets store. Never put one in a mobile app, web page code or a repository.
• Use separate keys for separate systems or environments, so you can revoke one without touching the others.
• An account can have up to 10 keys in use (revoked or expired keys do not count).

Replace a key#

1. Create a new key in the web app
2. Switch your system to the new key
3. Revoke the old key

A revoked or expired key stops working within 30 seconds (usually at once) and cannot be turned back on.

When a key has a problem#

Requests answered with these errors use no credit. Every code is listed in Error codes