Onboarding overview

Accessing the Education Data Platform is a four-step process: register your application, choose a subscription tier, retrieve credentials, and make your first authenticated call. The whole flow takes under five minutes for the standard tiers.

Your application's tier determines its rate limits and quota. The list of schools your application can access is set when you onboard and can be expanded later via your partner support channel.

Step 1: Register your application

From the Applications section of this portal:

1. Click New Application
2. Give it a descriptive name (e.g. "Production Dashboard Integration")
3. Choose a subscription tier (see comparison below)
4. Submit the request

You'll be issued a client_id and client_secret. Store the secret in a secrets manager — it's only shown once.

Step 2: Choose a tier

We offer three subscription tiers, each with different rate limits and quotas:

Free is suitable for development and small-scale integrations. Standard is right for most production use cases. Premium is for high-volume integrations such as analytics platforms or multi-tenant systems.

Step 3: Get an access token

Exchange your client_id and client_secret for a Bearer JWT using OAuth 2.0 client credentials:

curl --request POST \
  --url https://auth.example.com/oauth/token \
  --header 'content-type: application/json' \
  --data '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "audience": "https://api.example.com",
    "grant_type": "client_credentials"
  }'

The response contains an access_token — that's your JWT. It contains custom claims describing your tier and approved schools:

{
  "tier": "standard",
  "schools": ["oakwood-primary", "ravenscroft-high"],
  "client_id": "YOUR_CLIENT_ID",
  "iss": "https://auth.example.com/",
  "exp": 1780821709
}

Tokens are valid for one hour. Mint a fresh one before expiry or implement automatic refresh in your client.

Step 4: Make your first call

Use the access token in the Authorization header:

curl https://api.example.com/stats/v1/attendance/summary?school_id=oakwood-primary \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

The gateway:

• Validates the JWT signature against the identity provider's JWKS
• Maps the tier claim to a rate-limit policy
• Forwards the schools claim to the upstream service
• The upstream service enforces that the requested school is in your approved list

If everything checks out, you'll get a JSON response. If your token is missing a claim, expired, or invalid, you'll get a 401. If you try to query a school not in your approved list, you'll get a 403.

Authorisation model

Every authenticated request flows through three layers of checks:

1. Authentication — the JWT signature and expiry are verified at the gateway
2. Rate limiting — your tier's request and cost quotas are checked
3. School-level authorisation — the requested school_id is checked against your approved list

The third layer is enforced by the upstream services, with the approved list forwarded from the JWT as an X-Claim-Schools header. This means even if you bypass the rate limit, you can't access schools outside your approved set.

What to do if requests fail

Always include the X-Request-Id response header when contacting support — it lets us trace your request through all the systems involved.