Classroom identities, credentials and roles

Choose the identity deliberately

Identity	What it represents	Important limits
Human customer account	A teacher, co-teacher, billing person or ordinary class member	API key/OAuth scopes and current class role both apply. OAuth additionally needs effective third-party-app policy.
School student app session	A school-managed student in the separate student pool	Used by the Classroom app's opted-in session routes. It cannot manage developer keys, OAuth consent, billing or the school roster.
Managed member token	A fine-grained key owned by one student, issued by the class	Acts as that student, not the teacher or class. The public issue schema rejects `orgs:manage`; 1–30 day expiry; only the organisation manages it.
Organisation user token	The `class:<orgId>` principal at user level	Student-tier standing for organisation administration; document/permission scopes and at most `orgs:read`. This does not cap its own class-document access at viewer. No speech or live-room identity.
Organisation admin token	The same class principal at admin level	May carry `orgs:manage` and teacher-tier standing. It does not inherit a human owner's identity; organisation-owner checks still compare the actual owner field.
Isolated app test token	An operator-created `app:` test principal	Can only verify `/me` and list `/voices`; it cannot access any classroom.

Managed member tokens and organisation tokens are different products. The former are user-owned and cannot request organisation management. The latter are organisation-owned and have user/admin levels in the current working tree. Do not describe both as an unrestricted “school API key.”

The public /api/v1 wrapper accepts configured customer-pool session JWTs, API keys and Handwrite OAuth access tokens. It does not configure the student-pool JWT verifier. Do not copy a Classroom browser token into a public API request and expect it to authenticate. An authorised managed student key is a separate public-API credential; the student app uses session-aware routes.

Organisation tokens are currently created through the signed-in organisation Developer tab, not another public API key. The source requires a plan with the developer feature, current membership, the developerAccess policy and the creator's current standing. Class students never gain the Developer tab, even under everyone; billing does not gain it either. A teacher can create admin-level tokens. Co-teachers can create user-level tokens only when the policy permits managers. The current code caps token authority after role changes and refuses tokens whose creator loses access. These developer controls are source-verified; release/deployment is not established here.

Individual-document checks grant owner access when the document owner equals the token's own class: principal. Even a user-level org token can therefore create, edit, share or delete class-owned documents when its scopes, selected-document restrictions and effective policy permit; selected-document tokens cannot create new documents. The organisation listing calculates its access label from the token's role, so that label can differ from the individual-document ownership result. Do not apply the human student row below to an organisation service token.

Staff API-block enforcement is also a separate release check for these new org-owned tokens: their current authentication path omits the common staff-block gate used by member credentials. Do not treat a staff suspension as proof that every service token has stopped; verify token revocation or developerAccess: off when a complete stop is needed.

Classroom role matrix

These are human membership-role permissions, not substitutes for token scopes, entitlement or resource access. Organisation-owned tokens use the separate document ownership behavior described above.

Action	Teacher	Co-teacher	Billing	Student
Read class	Yes	Yes	Yes	Yes
Rename class	Yes	No	No	No
Delete ordinary class	Owning teacher only	No	No	No
Read visible memberships	Full roster	Full roster	Full roster	Teachers, co-teachers and self
Read membership emails when stored	Yes	Yes	Yes	No
Manage memberships	Valid non-owner targets/roles	Student tier only	No	Self-leave only if allowed and credential has scope
Create class-owned documents	Yes	Yes	No	No
Baseline class-document access	Owner	Owner	Viewer	Viewer
Read class policies	Yes	Yes	Yes	Own effective policy only
Change class-wide policies	Yes	No	No	No
Change member overrides	Yes	Student targets only	No	No
Issue/revoke managed student tokens	Yes	No	Yes	No
List managed-token administration	Yes	Yes	Yes	No
Read billing	Yes	No	Yes	No
Read member usage	Yes	Yes	Yes	Own view
Read collaboration insights	Full	Full	No	Own share
Erase school student through Students	Yes	No	No	No

A classroom has no developer role, although a school plan can include a developer feature. The class has one owner field; other teachers are admin tier but do not become the owner. The shared owner role value is a team ownership-transfer mechanism, not a class role.

A student can edit a document only when its actual access allows it, such as an explicit personal editor grant. Joining a live session does not automatically upgrade viewer access. Teacher/co-teacher owner-level access to class documents does not grant blanket access to students' unrelated personal documents.

Source basis: http.ts, console.ts, portal.ts, org-roles.ts, org-permissions.ts, managed-tokens.ts, policy-schemas.ts and developer.ts.

Classroom identities, credentials and roles

Choose the identity deliberately#

Classroom role matrix#

Choose the identity deliberately

Classroom role matrix