A partner API for school data.

Authentication

Every request carries a key-id header and an HMAC-SHA256 signature over timestamp + method + path + body. The secret is never sent. Requests with a timestamp older than 300 seconds are rejected.

X-EduCore-Key-Id:    ak_live_7Qp2R9
X-EduCore-Signature: t=1789632650,v1=9f...
Idempotency-Key:     4f0a1b2c-...

Versioning & deprecation

The version lives in the path, not a header. Breaking changes always become a new /api/v2/; adding an optional field is not a breaking change. An old version lives for 12 months after its replacement ships, and sends a Sunset header from day one.

Conventions

Money is a string with the currency at the same object level. Never sum across currencies: aggregate endpoints return an array of totals per currency, not a single number.

Error

All errors are RFC 9457 application/problem+json. Branch your logic on code — a stable SCREAMING_SNAKE string — not on the detail prose.

{
  "type":     "/errors/scope-denied",
  "title":    "Scope not granted",
  "status":   403,
  "detail":   "Key lacks roster.pii",
  "instance": "/api/v1/partner/_",
  "code":     "SCOPE_DENIED"
}

Webhooks & polling

Webhooks are the primary path. Register one HTTPS endpoint per environment, accept a signed POST, and answer 2xx within 5 seconds. Failures retry five times up to 6 hours; after that the event remains available by polling.

Endpoint

MCP

The POST /partner/mcp endpoint is a Model Context Protocol server (HTTP, sessionless JSON mode) behind the same authentication and rate limit as the other endpoints. It holds read-only tools; a key only sees the tools its scopes allow, and the rows returned are exactly those of REST: school limit, foundation limit, NIK only with roster.pii.

Before you start

1. Python 3.8 or newer on the computer that runs the AI client (python3 --version; on Windows use python).
2. Download educore_mcp_bridge.py and keep it in a permanent folder, for example ~/sekolahos/.
3. Check the file before running it: shasum -a 256 educore_mcp_bridge.py must print 177f51df1cb11dea603f32a03809fca400a4f0e5e5dfbabf378f50d3f3a0c080.
4. Ask the foundation admin to issue a key. Note the key-id and secret; the secret is shown only once.
5. Keep the secret in a password manager or the operating system keychain, not in a synced file or in git. Ask for a key with only the scopes you need and restrict it with an IP list.

Guide by client

{
  "mcpServers": {
    "sekolahos": {
      "command": "python3",
      "args": ["/Users/anda/sekolahos/educore_mcp_bridge.py"],
      "env": {
        "EDUCORE_API_BASE": "https://schoolday.live/api/v1/",
        "EDUCORE_KEY_ID": "ak_test_...",
        "EDUCORE_KEY_SECRET": "..."
      }
    }
  }
}

claude mcp add sekolahos \
  --env EDUCORE_API_BASE=https://schoolday.live/api/v1/ \
  --env EDUCORE_KEY_ID=ak_test_... \
  --env EDUCORE_KEY_SECRET=... \
  -- python3 ~/sekolahos/educore_mcp_bridge.py

EDUCORE_API_BASE=https://schoolday.live/api/v1/ \
EDUCORE_KEY_ID=ak_test_... EDUCORE_KEY_SECRET=... \
npx @modelcontextprotocol/inspector python3 educore_mcp_bridge.py

Quick test from the terminal

Send one JSON-RPC message to the bridge; the reply lists the tools your key may use:

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | python3 educore_mcp_bridge.py

Available tools

Every tool accepts limit (at most 200) and before_id. The answer carries next_before_id; pass its value to get the next page. There are no write tools; webhook registration stays REST-only. One key may call tools at most 120 times per minute (within the 600 request limit).

If it does not work

For resellers and integrators

Every API key works for exactly one foundation; no key reaches several foundations. If you integrate many schools, ask each foundation's admin to issue you a key in the console, under Partners & API keys, with the narrowest scope possible. Keep each secret in your own vault, one per foundation.

To help with configuration inside the console, the foundation admin creates an ordinary staff login with only the roles needed. A reseller gets no cross-foundation access.

Rate limits

Going over a limit returns 429 RATE_LIMITED with a Retry-After header.