Get started

Authentication

Every request carries your secret key as a bearer token. The key identifies your organisation and decides what the request may do.

curl https://www.bitraffle.io/api/v1/competitions \
  -H "Authorization: Bearer $BITRAFFLE_SECRET_KEY"

const res = await fetch("https://www.bitraffle.io/api/v1/competitions", {
  headers: { Authorization: `Bearer ${process.env.BITRAFFLE_SECRET_KEY}` },
});
const { data } = await res.json();

import os, requests

res = requests.get(
    "https://www.bitraffle.io/api/v1/competitions",
    headers={"Authorization": f"Bearer {os.environ['BITRAFFLE_SECRET_KEY']}"},
)
data = res.json()["data"]

#Secret keys

• A secret key is sk_ followed by 48 hexadecimal characters. Its first 11 characters (for example sk_4f3a9c1e) are its public prefix: that is how it appears in your admin's audit log, and what signed draw requests name as their subject.
• It is shown once, when it is issued. We store only a hash of it, so we cannot show it again.
• Keep it server-side. A key in a browser, an app bundle or a public repository can be used by anyone who finds it.
• Every write made with a key lands in your organisation's audit log under api-key:<prefix>, next to changes made in the admin.

#Scopes

A key may only call the endpoints its scopes allow; anything else returns 403 insufficient_scope, naming the scope it needed in required.

New keys carry competitions:read and winners:read. Write scopes are granted deliberately, when the key is issued.

#Signed requests for draws

The draw endpoints ask for more than a bearer key: each request also carries a short-lived BitRaffle-Proof header that you sign with a private key only you hold. A leaked secret key alone cannot run draws on your account. See Signed requests.

#Authentication errors