Sending a key
Send the key as a bearer token on every request. There is no other authentication scheme, no query parameter and no cookie.
curl https://api.klasstack.com/v1/school \
-H "Authorization: Bearer ks_test_sk_your_key_here"Key formats
| Prefix | Kind | Where it belongs | What it does |
|---|---|---|---|
| ks_test_sk_... | Secret, test mode | Servers only | Answers from the documented example. Never billed, never touches school data. |
| ks_live_sk_... | Secret, live mode | Servers only | Reads and writes real school data. Billed per call. |
| ks_live_pk_... | Publishable, live mode | Safe to embed | Locked to your allowed web origins and mobile bundle ids. Reaches a curated public set of endpoints only. |
Test mode and live mode
- A test key answers from the endpoint example the reference publishes. Nothing runs and nothing is billed.
- Test keys are issued the moment you create an app, so you can build the whole integration before going live.
- A live key requires the school to be KYC approved and the app switched live. An admin does that, with an MFA re-check.
- A live call reads and writes real data, fires the same automations a dashboard write fires, and is billed.
Rotation
Rotation is one click in the Developer section. It issues a second key, shown once, while the old key keeps working until you revoke it. There is no timer: the old key never expires on its own. So rotation is two steps. Deploy the new key everywhere, confirm every server is using it, then revoke the old key. Until you do that second step, both keys are live. Rotate whenever a person who saw the key leaves the project, and on a schedule of your own besides.
Revocation
Revoking a key stops it at once, on every server. Calls made with it answer 401 invalid_api_key from that moment. Revocation is the only thing that stops a key: rotation alone leaves the old one live. Keys belong to the app, not to a person, so removing a vendor from the school does not stop their integration. Rotate the keys that vendor saw, move your servers onto the new keys, then revoke the old ones.
Scopes
An app holds scopes shaped service plus access, such as students:read or attendance:write. A call to an endpoint outside the app scopes answers 403 insufficient_scope. Write access, billable services and money-out services are admin approved. Grant the narrowest set that works.