Authentication, rate limits, and errors
The integration surface is small and consistent. This page covers the conventions that apply across it: how machine-to-machine endpoints authenticate, the rate limits, and the error shapes to expect.
Authentication
The server-to-server endpoints you'll integrate with, chiefly
SIS sync, authenticate with a bearer
token: a shared secret your institution admin generates in the console
(Settings → Integrations), sent in the Authorization header.
POST /api/sis/sync
Authorization: Bearer <your-institution-secret>
Content-Type: application/jsonTokens are verified with a timing-safe comparison, so a wrong secret leaks no information about how wrong it was. Treat the secret like any production credential: store it in your secrets manager, never in source control, and rotate it if it may have been exposed.
End-user surfaces (the student app and staff console) authenticate with an HttpOnly session cookie established at sign-in, not a bearer token. See the OIDC flow. You won't call those as an integrator; the machine endpoints are the integration surface.
Rate limits
Endpoints are rate-limited per client. The limits are sized for legitimate use, so a well-behaved integration won't hit them:
| Endpoint | Limit |
|---|---|
SIS sync (/api/sis/sync) | 20 requests / minute |
Knowledge Base MCP (knowledge.firstsix.com.au/api/mcp) | 300 requests / minute per IP |
Console MCP (/api/mcp on the console) | 130 requests / minute per connection before any lookup, then 120 per connection and 240 per person across their connections. No per-IP limit: a token the console did not issue is refused before any lookup |
Console MCP sign-in (/api/oauth/token) | 5 / minute per code or refresh token and 20 renewals / hour per connection, with no per-IP limit (a code or token the console did not issue is refused before any lookup) |
Console MCP registration (/api/oauth/register) | None when Claude or ChatGPT registers again at its own callback address (it gets its existing registration back); every other registration, hosted or on your own computer, 60 / hour per IP |
Console MCP disconnect (/api/oauth/revoke) | 10 / minute per connection and per token; a token the console did not sign is answered without any lookup, except one in the shape used before October 2026, which anyone can make up and which is limited to 30 / minute per IP until those tokens have expired |
| Console MCP connections (per staff member) | At most 10 live connections per person. An eleventh is refused on the consent screen, and nothing is disconnected to make room; disconnect one in Your account first |
Exceed a limit and you get 429 Too Many Requests with a Retry-After header
(seconds). Back off for that long and retry. Don't hammer.
The console's MCP limits are kept in a shared store. In production, if that
store is unavailable, the limits on /api/mcp, /api/oauth/token,
/api/oauth/register and the consent screen's Connect step refuse with 503
and {"error": "rate_limit_unavailable"} rather than fall back to weaker
per-server counts. Retry later. The disconnect endpoint (/api/oauth/revoke)
is never refused this way, because a refused disconnect would leave alive a
token its holder was trying to end.
Sizes and idempotency
- SIS sync accepts up to 5,000 students per request; a larger batch returns 413. Page your roster into batches under that cap.
- SIS sync is idempotent. Re-sending the same students reconciles in place rather than duplicating, so retries after a network blip are safe.
Error shape
Errors return a JSON body with a stable, snake-case error code and sometimes a
human-readable detail. (The Knowledge Base MCP server is the exception: it speaks
JSON-RPC, so its errors use JSON-RPC's own shape, described on
its page.)
{ "error": "batch_too_large", "max": 5000 }Common status codes across the surface:
| Code | Meaning |
|---|---|
200 | Success |
400 | Malformed JSON or a missing required field |
401 | Missing or incorrect bearer token |
413 | Payload too large (e.g. over the batch cap) |
429 | Rate limited. Honour Retry-After |
500 | Server-side failure |
503 | Endpoint not configured (a required secret isn't set), or, on the console's MCP endpoints, the rate-limit store is unavailable (rate_limit_unavailable) |
The error codes are stable; the human-readable messages may be reworded. Write
your integration to switch on the code (and the HTTP status), and log the message
for humans.
Common questions
Is there a sandbox environment?
Integration happens against your institution's tenant. There's no separate public sandbox; coordinate test runs (for example a small SIS batch to a test cohort) during onboarding.
Do you offer outbound webhooks?
Yes. Outbound webhooks are in early access: per-tenant endpoints receiving HMAC-signed help-request events, configured in the console. See Webhooks.
How do I rotate the secret?
Your institution admin rotates it in the console, on the same panel that generated it. The old secret stops working the moment the new one is issued, so update your secrets manager and your scheduled push together. Rotate promptly if exposure is suspected.
Related
The fastest answer is usually one question away.