Authentication

Send the key as a Bearer token#

Every request needs this header:

Authorization: Bearer qk_0123456789_AbCdEfGhIjKlMnOpQrStUvWxYz012345

Requests without it are answered with 401 authentication_failed. Keys in the URL (?api_key=…) are not accepted, because URLs end up in logs.

Key format#

A key is 46 characters: qk_, a 10-character public prefix in hexadecimal, an underscore, and a 32-character secret.

qk_0123456789_AbCdEfGhIjKlMnOpQrStUvWxYz012345
└┬┘└───┬────┘ └──────────────┬───────────────┘
 │   prefix (shown in lists)   secret (shown once)
 └ Quilo key

The qk_ start makes keys easy to find with secret scanners (GitHub secret scanning, gitleaks, trufflehog). Add a rule for qk_[0-9a-f]{10}_[A-Za-z0-9_-]{32}.

What happens with each request#

1. Quilo computes the SHA-256 fingerprint of the key and looks it up. The key itself is never stored or logged.
2. It checks that the key is not revoked or expired, that API access is on for the company, that the company is not suspended, and that the key's owner is still an active member.
3. It counts the request against the key's per-minute limit.
4. It runs your request as the key's owner for at most 60 seconds, so the same row-level security rules apply as in the app. A read-only key carries a read-only mark that every write rule refuses.
5. It logs the method, path, status, duration and request ID (no bodies, no query values).

Store keys safely#

• Keep keys in environment variables or a secret manager (GitHub Actions secrets, Vercel/Netlify environment variables, Docker secrets, 1Password, AWS Secrets Manager…).
• Never commit a key to Git, paste it into a ticket or chat, or put it in a spreadsheet cell others can read.
• Never put a key in a website, mobile app or browser extension. Anyone can read it there. Call Quilo from your server instead.
• Use one key per integration and name it after the integration. If one leaks, you revoke only that one.
• Give each key the least access it needs: read only for reports, an expiry for experiments.

Rotating a key without downtime#

1. Create a new key with the same access.
2. Put it into the integration's configuration and deploy.
3. Check Last used on the API keys page: the old key stops being used.
4. Revoke the old key.

If a key leaked#

1. Revoke it at once under Settings → API keys (owners and admins: Everyone's).
2. If you don't know which key leaked, an owner or admin clicks Switch API off, then creates new keys and switches the API on again.
3. Look at Recent requests and Settings → Security & activity for requests you don't recognise, and check the records that were changed.