Roster mapping protocol — school, EduSpaze, vendor

How a school's staff and pupils come to exist correctly inside a vendor's app, stay correct for a year, and disappear cleanly at the end of it. Both the school and the vendor are asked to comply with this. EduSpaze provides the mechanism and holds both sides to it. Last updated 2026-09-06.

Read alongside the vendor integration guide (the technical contract) and the school admin guide.

1. The agreement in one paragraph

The school owns identity. EduSpaze brokers it. The vendor never receives it. A pupil and a member of staff reach a vendor app as a *code* — RB-4213, STF-0007 — together with the school's id and the codes of the classes they belong to. No name, no email address, no date of birth, ever. The vendor builds its accounts on those codes; the school keeps them stable; EduSpaze guarantees that the same code means the same person on the launch, in the roster and in the telemetry that comes back.

Everything below exists to make one sentence true: the vendor can always answer "which class is this person in", and can never answer "who is this person".

2. The four things being mapped

Pupil and staff subjects share one namespace, so a vendor keeps one subject column and one account table for both. Subjects are unique within a school: two schools may both use STF-0001, and the pair (tenant, subject) is the real key.

3. The lifecycle

Eight stages. Each names what each party does, and what EduSpaze records.

S0 · Agreement

Nothing in this protocol overrides the DSA; where they differ, the DSA wins and EduSpaze should be told so this document can be corrected.

S1 · The school prepares its roster

The school imports pupils (School → Students → Import, CSV) with externalId taken from its SIS. This is the moment that decides whether the next twelve months work — see §4.

Staff already exist as accounts; EduSpaze mints STF-nnnn for each the first time one is needed, or the school can set its own staff codes.

S2 · The school approves the app, and its scope

The school decides which pupils may use the app — by class, by group, or by year — and that decision creates the connections. A pupil with no connection does not exist to that vendor: they are absent from the roster, refused on launch, and rejected in telemetry.

Staff scope follows pupil scope. A member of staff may open a vendor app when they teach a class that is in scope. That is deliberate: it needs no second list to maintain, and it cannot grant a teacher access to a cohort they do not teach.

S3 · Credentials and the handshake

A vendor that cannot verify a signature must not be given a key. This is the one step where "we'll fix it later" ends with pupils in the wrong classes.

S4 · Provisioning — the vendor builds its accounts

The vendor creates accounts before anyone arrives. A first launch should find an account waiting, not create one in a hurry with whatever the URL happened to contain.

S5 · First launch

A pupil opens the app from the EduSpaze launcher; a teacher opens it from School → Connected Apps. Both arrive through the same signed handshake.

A launch is an authentication, not a provisioning event. A subject the vendor does not recognise means its roster is stale: re-sync, then admit them. It never means "create an account for whoever this is".

S6 · Steady state

S7 · Change during the year

The rule underneath all of it: the subject is the person; the class is where they are today. A vendor that keys accounts on the class, or on a name it inferred, breaks at the first move.

S8 · Exit

An erasure request for one pupil follows the same path: the school anonymises the pupil in EduSpaze, the subject stops resolving, and the vendor deletes on that signal. Historic engagement stays as time-only, attached to a token that no longer identifies anybody.

4. What each party must comply with

The school must

1. Give every pupil a stable externalId from the SIS, and never reuse or renumber it. This is the single obligation that everything else rests on. A re-import that changes the codes makes every pupil a stranger to every vendor and orphans their history.
2. Keep class and group assignments current — they are what the vendor places people by.
3. Approve and review scope by class or group each term, and revoke through the platform.
4. Never send a pupil's name, email or date of birth to a vendor out of band. If a vendor asks for one, tell EduSpaze: it is a breach of the DSA, not a favour.
5. Keep a school administrator with a password, so a provider outage cannot lock the school out of its own settings.

The vendor must

1. Key every account on (tenant, subject). Not on a name, not on an email, not on a class, not on an order of arrival.
2. Verify the launch signature before trusting anything in the URL, reject a launch older than five minutes, and refuse a repeated nonce.
3. Provision only from the roster. No self-signup, no invite links, no "just add this one pupil" inside a school's tenant.
4. Treat a subject that has left the roster as revoked, and delete within the agreed window.
5. Send no content. Telemetry carries when and how long, never what: no scores, no work, no free text. There is no field for it, and inventing one is a breach.
6. Never attempt re-identification — not by cross-referencing, not by asking a pupil their name, not by inference from a class label.
7. Tell EduSpaze before changing how it verifies launches, and opt in to v2 only after its verifier signs whatever it receives rather than a fixed list of parameters.

EduSpaze will

1. Guarantee that one subject means one person, for as long as the school keeps its codes stable, across launch, roster and telemetry.
2. Answer a vendor only about its own connected pupils, in the tenant it names.
3. Refuse — identically and without explanation — any launch outside a verified domain, an inactive configuration, or a lapsed subscription, so no probe learns anything.
4. Record every launch, every scope change, every revocation and every roster read on the school's own audit log, and show the school what each vendor was told.
5. Never publish a change to the v1 launch contract. A vendor's working integration stays working; new information arrives only in a version they opt into.
6. Show the school, in its own portal, exactly what a vendor is told about a pupil and a member of staff, in the same words as this document.

5. What is never shared

If a vendor's product genuinely needs something on the right-hand column, that is a conversation with EduSpaze and the school before a line of code — not a field added to a payload.

6. When it goes wrong

Whoever notices, tells EduSpaze. The audit log settles what actually happened, because both the launch and the roster read are on it.

7. What EduSpaze still has to build for this

Stated plainly, because the protocol above describes the intended process and part of it is not yet self-service:

The first two are what make this document enforceable rather than aspirational.