Add an existing person to a class

POST /api/v1/orgs/{id}/members · Operation ID: addMember

Application use

Use an existing user principal and a valid class role. A teacher can assign class roles; a co-teacher can add only students. This creates a membership, not a managed school student account. Use the school Students workflow for school-owned identities. The route checks seats and existing membership; it is not an account lookup endpoint.

Authentication and permission

Bearer credential with orgs:manage. Teacher or co-teacher with members.manage and orgs:manage; assignable roles are narrowed by the caller.

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 POST 'https://handwrites.io/api/v1/orgs/REPLACE_ORG_ID/members' \
  -H "Authorization: Bearer $HANDWRITE_API_TOKEN" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"principal":"user:REPLACE_USER_ID","role":"student"}'

Parameters

Name	In	Required	Details
`id`	path	Yes	An organisation ID (org_…).
`Idempotency-Key`	header	No	1–255 visible ASCII characters (a UUID per operation). A retry with the same key and identical request within 24 hours replays the first 2xx response with Idempotent-Replayed: true; a different request with the key gets 422 idempotency_mismatch; a retry while the first runs gets 409 idempotency_in_progress.

Request body

application/json (required).

Field	Required	Details
`principal`	Yes	A person.
`role`	Yes	Team roles: owner, admin, billing, manager, developer, member. Class roles: teacher, co-teacher, billing, student.

Responses and recovery

Status	Meaning	Format
201	The membership.	application/json
400	invalid_request (the message names the field), validation_failed.	application/json
401	unauthorized: no token, or it's invalid, revoked or expired.	application/json
403	insufficient_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
404	not_found: it doesn't exist or you can't see it (never 403 for documents you can't see).	application/json
409	conflict (changed meanwhile, already a member) or idempotency_in_progress (with Retry-After).	application/json
422	limit_reached, idempotency_mismatch, unreadable_file, no_text, empty_document.	application/json
429	rate_limited (burst or daily cap) or quota_exceeded (no characters left).	application/json
500	internal_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.

README — POST /api/v1/orgs/{id}/members

Add an existing person to a class#

Application use#

Authentication and permission#

Example#

Parameters#

Request body#