Start here

Authentication

Server to server, with an institution API key. A school administrator creates one under Settings, Integrations, and it is shown exactly once. Send it as the X-API-Key header on every request. There is no password anywhere in the loop, and the key belongs to the institution rather than to a person, so it keeps working when that person leaves.

A key carries the same per-section access a staff account does. A key made for roster sync cannot approve a verification, and that is enforced on every route rather than by convention.

Rotating a key does not need an outage. Rotation issues a replacement and leaves the old key working for a set overlap, thirty days by default. Both authenticate during the window, so you deploy the new value when it suits you rather than racing a revocation. The old key then expires on its own, or the school revokes it as soon as you confirm the switch.

Test mode

Every institution can issue a test key, which runs against a sandbox copy of that institution holding invented students. Nothing a test key does reaches a real student, and nothing it does is billed.

Everything else is identical: the same routes, the same permissions, the same rate limits, the same webhooks. Build against the sandbox, then change one header value.

Webhooks, not polling

Register an HTTPS endpoint and we POST to it when something happens. Every request carries an X-Signature header, an HMAC of the timestamp and the raw body under your endpoint's own signing secret. Verify it against the raw bytes: re-serialising the JSON changes them and the digest will not match.

Delivery is at least once, order is not guaranteed, and a failed delivery is retried six times over about half an hour. Deduplicate on the message id and treat each message as a statement of current fact. The full event catalog, with the fields in each payload, is inside the product next to the page where you register the endpoint.

Four responses that are not failures

Getting any of these wrong produces a client that quietly reports the wrong thing.

What the schema covers today

52 operations carry a full request and response contract, out of roughly 120 routes. The rest appear in the schema with their paths, methods and parameters but an unspecified response body, and we are annotating them steadily. The integration surface, meaning everything an outside system actually calls, is the part that is specified.

That number is measured from the running schema rather than written down here, and a test refuses to let it fall.

Versioning

Routes live under /api/v1/. Within a version we add fields and add endpoints; we do not remove a field, rename one, or change what a value means. Parse permissively and ignore keys you do not recognise, because new ones will appear without notice. A change that would break a client gets a new version, not a new deploy.

Rate limits

Each API key has its own per-minute limit, set by the school when it creates the key, so one runaway integration cannot throttle that institution's own portal. Verification endpoints additionally draw on a weighted per-student budget, because submitting capture frames costs many times what starting an attempt does. Both answer 429 with a retry hint.

Something missing?

If a route you need has no documented response body yet, ask and we will annotate it. That is a day of work, not a roadmap item. Contact us.