1. People
Handwrite Classroom
  • Handwrite Classroom
    • Start here — Classroom for developers
    • Classroom API specification notes
    • Classroom socket specification notes
    • Classroom live socket — README
    • Classroom identities, credentials and roles
    • School and student workflows
    • Classroom policy and data-use notes
    • Class setup
      • README — GET /api/v1/orgs
      • README — POST /api/v1/orgs
      • README — GET /api/v1/orgs/{id}
      • README — PATCH /api/v1/orgs/{id}
      • README — DELETE /api/v1/orgs/{id}
      • Class setup API — README
      • Choose a class from the returned organisations
      • Create an ordinary class
      • Read the selected class
      • Rename a class
      • Delete an ordinary class
    • Invitations
      • README — GET /api/v1/orgs/invitations
      • README — POST /api/v1/orgs/invitations/{inviteId}/accept
      • README — POST /api/v1/orgs/invitations/{inviteId}/decline
      • README — GET /api/v1/orgs/{id}/invitations
      • README — POST /api/v1/orgs/{id}/invitations
      • README — DELETE /api/v1/orgs/{id}/invitations/{inviteId}
      • Invitations API — README
      • Read invitations to the signed-in person
      • Accept a class invitation
      • Decline a class invitation
      • List pending class invitations
      • Invite a person by email
      • Cancel a pending invitation
    • People
      • README — GET /api/v1/orgs/{id}/members
      • README — POST /api/v1/orgs/{id}/members
      • README — PATCH /api/v1/orgs/{id}/members/{principal}
      • README — DELETE /api/v1/orgs/{id}/members/{principal}
      • README — POST /api/v1/orgs/{id}/leave
      • People API — README
      • Read the visible membership roster
        GET
      • Add an existing person to a class
        POST
      • Change a class member role
        PATCH
      • Remove an ordinary class membership
        DELETE
      • Leave an ordinary class
        POST
    • Documents
      • README — GET /api/v1/orgs/{id}/documents
      • Documents API — README
      • List class-owned documents
    • Plan and usage
      • README — GET /api/v1/orgs/{id}/billing
      • README — GET /api/v1/orgs/{id}/usage
      • README — GET /api/v1/orgs/{id}/usage/live
      • README — GET /api/v1/orgs/{id}/members/{principal}/usage
      • README — GET /api/v1/orgs/{id}/insights
      • Plan and usage API — README
      • Read classroom plan and seat information
      • Read classroom usage totals
      • Read the recent classroom activity window
      • Read one member usage
      • Read classroom collaboration insights
    • Policies
      • README — GET /api/v1/orgs/{id}/policies
      • README — PUT /api/v1/orgs/{id}/policies
      • README — GET /api/v1/orgs/{id}/members/{principal}/policy
      • README — PUT /api/v1/orgs/{id}/members/{principal}/policy
      • README — DELETE /api/v1/orgs/{id}/members/{principal}/policy
      • Policies API — README
      • Read class-wide policy
      • Replace class-wide policy rules
      • Read one member policy
      • Replace one member policy override
      • Clear one member override
    • Managed tokens
      • README — GET /api/v1/orgs/{id}/members/{principal}/tokens
      • README — POST /api/v1/orgs/{id}/members/{principal}/tokens
      • README — DELETE /api/v1/orgs/{id}/members/{principal}/tokens/{tokenId}
      • Managed tokens API — README
      • List tokens issued to a member
      • Issue a managed student token
      • Revoke a managed token
  1. People

README — PATCH /api/v1/orgs/{id}/members/{principal}

Change a class member role#

PATCH /api/v1/orgs/{id}/members/{principal} · Operation ID: changeMember

Application use#

Class roles are teacher, co-teacher, billing and student. owner is a team transfer value, not a class role or a classroom ownership-transfer API. The owning teacher cannot be demoted through this route. Co-teachers can manage only student-tier targets. Promoting a student out of the member tier revokes their managed tokens.

Authentication and permission#

Bearer credential with orgs:manage. Teacher, or co-teacher for student-tier targets and student role, plus orgs:manage.
Scopes, membership, current role, effective policy and applicable plan checks all apply. A managed student token cannot grant organisation-management authority. A student-pool login JWT is not a public-API bearer credential. See Classroom identity and roles.

Example#

Replace placeholders using an authorised disposable test class. Mutation examples change real data when run. Keep tokens on the server; never copy student credentials into diagnostics.
curl --fail-with-body -X PATCH 'https://handwrites.io/api/v1/orgs/REPLACE_ORG_ID/members/user%3AREPLACE_USER_ID' \
  -H "Authorization: Bearer $HANDWRITE_API_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"role":"student"}'

Parameters#

NameInRequiredDetails
idpathYesAn organisation ID (org_…).
principalpathYesA principal, URL-encoded (user%3A…).

Request body#

application/json (required).
FieldRequiredDetails
roleYesIn a team, the owner may send owner to transfer it.

Responses and recovery#

StatusMeaningFormat
200The membership.application/json
400invalid_request (the message names the field), validation_failed.application/json
401unauthorized: no token, or it's invalid, revoked or expired.application/json
403insufficient_scope, forbidden (you can see it but not do this), app_test_restricted, account_deleted (the account is scheduled for deletion; any request).application/json
404not_found: it doesn't exist or you can't see it (never 403 for documents you can't see).application/json
429rate_limited (burst or daily cap) or quota_exceeded (no characters left).application/json
500internal_error.application/json
The paired API reference holds the shared machine-readable schema. Additional role, policy, seat and plan failures are described in API specification notes. Do not parse 204 or 304 responses as JSON, and do not treat 403 as a transient retry.
Modified at 2026-10-26 13:24:24
Previous
README — POST /api/v1/orgs/{id}/members
Next
README — DELETE /api/v1/orgs/{id}/members/{principal}
Built with