Authentication
Scoped API keys, and how to hold them without regretting it.
ProposedNot yet callable
This documents a design under review. Endpoints, payloads and field names may change before release.
API keys
Keys are issued per institution and sent as a bearer token on every request.
curl https://api.onetaplabs.com/v1/attendance \
-H "Authorization: Bearer sk_live_4bc19..."A missing or unrecognised key returns 401. A valid key without the required scope returns 403, and the message names the scope it wanted.
Scopes
| Scope | Grants |
|---|---|
| attendance:read | List and retrieve records and sessions. |
| attendance:write | Create and correct records. |
| presence:read | The live presence endpoints. |
| webhooks:manage | Register, roll and replay webhook endpoints. |
Issue one key per integration, with the narrowest scope that works. A reporting dashboard needs attendance:read and nothing else — if that key leaks into a notebook or a frontend bundle, the damage is bounded to reading.
Live and test keys
Test keys (sk_test_) run against isolated data. They never touch a real roll, so they are what belongs in CI and in a developer’s shell history.
sk_live_... real institution data
sk_test_... sandbox data, safe to breakHandling keys safely
- Keys are shown once at creation. Store them in your secret manager, not in the repository.
- Never call this API from a browser. A key in frontend JavaScript is a public key. Proxy through your own server.
- Roll a key the moment it is exposed. Old and new keys overlap for 24 hours so you can deploy without downtime.
- Every request is logged with its key id, so a leaked key’s activity can be audited after the fact.