API Keys & the Read API

An API key lets an outside tool read your school's MarkBook data. Schools use keys for dashboards (Power BI, Looker Studio), data warehouses and scheduled exports. The key can only read. It cannot enter a mark, change a setting or publish a report.

This page is for the MarkBook administrator and school IT. You need the permission Developer: API keys and webhooks to create keys.

What a key can and cannot do

• Read-only. Every scope is read-only. A person is always behind an action like entering a mark or publishing a report.
• One school. A key is tied to your school when you create it. It cannot read another school, whatever the request says. Asking for another school's record returns "not found".
• No student names. Students appear only as Kinderpedia IDs. Names stay in Kinderpedia.
• No free text in bulk. Comment columns and text-typed columns are left out of the marks feed. Teacher prose about a child is not analytics data.

Create a key

1. Open Configuration → Developer and choose the tab API keys.
2. Press Generate API key.
3. In What is it for, name the tool that will hold the key, for example "Power BI weekly marks". In a year, this is how someone decides if the key is still needed.
4. Under What it may read, tick the scopes the tool needs. Give no more than it needs.
5. Choose Expires: Never, In 90 days or In a year.
6. Create the key and copy it.

WARNING

The key is shown once. MarkBook stores only a hash, so it cannot show the key again. Copy it into the tool straight away. If you lose it, revoke it and make a new one.

A key that expires fails on a known date. A key that never expires outlives the reason it was made. Prefer an expiry.

Scopes

Scope	What it lets the tool read
Markbooks and mark entries	Markbooks and their marks
Reports	Report-card status and metadata, never the document
Targets	The per-student target register
Configuration	Subjects, periods and years
Outcomes	Curriculum frameworks, learning outcomes and the judgements recorded against them
Standards	The standards library and outcome-to-standard mappings
Analytics	Counts and distributions only. No student rows
Published reports	Published report metadata only. Drafts stay invisible

Use a key

Send the key in a header on every request:

Authorization: Bearer <your key>

To check a key works, request /api/v1/health on your MarkBook address. A valid key gets an answer. An invalid, revoked or expired key gets "unauthorised".

The main feeds are:

Feed	What it returns
/api/v1/academic-years, /reporting-periods, /subjects	The school's calendar and subjects
/api/v1/templates, /value-types, /grade-scales, /assessment-scales	How markbooks are set up
/api/v1/markbooks	The markbooks
/api/v1/marks and /api/v1/markbooks/{id}/marks	The marks
/api/v1/targets	Student targets
/api/v1/reports, /api/v1/reports/published	Report status
/api/v1/outcome-frameworks, /outcomes, /outcome-evaluations	The curriculum and its judgements
/api/v1/standard-frameworks, /standard-statements, /outcome-standard-mappings	Standards
/api/v1/analytics/...	Grade bands, distributions, coverage, report status
/api/v1/deletions	What was deleted since a date

The full list, with fields, is in API Docs in the MarkBook menu.

Paging and syncing

• Lists come in pages of up to 200 rows.
• Most lists accept updated_since so a tool fetches only what changed. A date that cannot be read returns an error. It never returns the whole data set by mistake.
• /api/v1/marks pages with a cursor. Each answer gives the cursor for the next page. This stays fast however far a full sync has gone. Use the cursor rather than an offset. Send only one of the two.
• /api/v1/deletions?since= lists removed records, so a warehouse can delete them too.
• Each key may make 600 requests a minute. Beyond that the answer is "too many requests"; wait and try again.

Manage keys

The API keys tab lists each key with its Name, Prefix, Scopes, Last used and Status (Active, Revoked or Expired).

• Revoke stops a key at once. The record stays so you can see what happened.
• Delete removes a revoked or expired key from the list.

Review the list each term. Revoke any key for a tool you no longer use.

TIP

Use one key per tool. If one tool is compromised, you revoke one key and the others keep working.

Data protection

A key is a standing credential, and data that leaves MarkBook is outside its controls. Before you create a key, check that:

• the receiving tool is approved by your school,
• the scopes match a real need, and
• you know who holds the key.

Creating and revoking keys is recorded in the activity log.

Was this helpful?