Skip to content
Open the app

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/json
Secrets are compared in constant time

Tokens 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:

EndpointLimit
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:

CodeMeaning
200Success
400Malformed JSON or a missing required field
401Missing or incorrect bearer token
413Payload too large (e.g. over the batch cap)
429Rate limited. Honour Retry-After
500Server-side failure
503Endpoint not configured (a required secret isn't set), or, on the console's MCP endpoints, the rate-limit store is unavailable (rate_limit_unavailable)
Branch on the code, not the message

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.

Was this helpful?
Need more help?

The fastest answer is usually one question away.

Contact us
Edit this page on GitHub