Authentication & scopes
Every request authenticates with a club API key sent as a Bearer token. A key belongs to the club (not to the administrator who created it) and can only ever reach that club's data.
Authorization: Bearer ct_live_...Key model
- Keys are created, rotated and revoked by club administrators in the app (System → API).
- Only a hash of the key is stored server-side; the full key is visible once, at creation.
- Keys do not expire by default. They keep working if the administrator who created them leaves the club.
- Keys are club-scoped: tenant isolation is enforced on every query,
so a key can never read or write another club's data (unknown ids answer
404). - Cookie sessions and app login tokens are not valid on
/api/v1, and API keys are not valid anywhere else.
Scopes
A key carries one or more scopes; a *:write scope implies the matching
*:read. Requests outside the key's scopes answer
403 insufficient_scope.
| Scope | Grants |
|---|---|
members:read | List and read members |
members:write | Create, update, delete members + bulk |
groups:read | List and read training groups |
events:read | List and read calendar events |
events:write | Create, update, delete events |
competition:read | Seasons and competition teams (read) |
competition:write | Manage competition teams |
attendance:read | Read attendance records |
attendance:write | Upsert attendance + bulk |
kennismakers:read | List and read trial members (intake) |
kennismakers:write | Create and update trial members — e.g. a website signup form |
Least privilege. Give each integration its own key with only the scopes it needs — that keeps the audit trail readable and limits the blast radius of a leak.
Rotation
Rotate a key in the app (System → API → Rotate): you get a new key with the same label and scopes, and the old key keeps working for 24 hours so you can switch your deployment over without downtime.
If a key leaks
- Revoke it immediately in the app — revocation is instant.
- Create a replacement key and update your integration.
- Review the club's audit log (System → Audit log): all API writes are attributed
to the key prefix, e.g.
api:ct_live_3f9K.
Plan gating
The public API is a Pro feature. If the club moves to a
lower plan, requests answer 403 upgrade_required; keys are blocked, not
deleted, and resume working after an upgrade.