1. Membership
Handwrite Team
  • Handwrite Team
    • Teams
      • 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}
      • Your teams and classes
      • Create a team or class
      • One of your organisations
      • Rename a team (owner or admin)
      • Delete with its memberships, invitations, documents and shares (owner)
    • Membership
      • 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}/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
      • README — GET /api/v1/orgs/{id}/invitations
      • README — POST /api/v1/orgs/{id}/invitations
      • README — DELETE /api/v1/orgs/{id}/invitations/{inviteId}
      • Organisation invitations to your verified email
        GET
      • Join with the invited role
        POST
      • Decline an organisation invitation
        POST
      • Members (students see teachers and themselves)
        GET
      • Add a person (managers)
        POST
      • Change a role; owner transfers a team
        PATCH
      • Remove a member (managers) or yourself
        DELETE
      • Leave (not the owner)
        POST
      • Pending email invitations (managers)
        GET
      • Invite an email (managers)
        POST
      • Withdraw an invitation (managers)
        DELETE
    • Documents
      • README — GET /api/v1/orgs/{id}/documents
      • Documents the organisation owns
    • Billing 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, status and seats per role (billing.read)
      • Usage per day and member (admins, managers, billing)
      • The last 60 minutes per member (admins, managers, billing)
      • One member's usage (usage.read, or yourself)
      • How people collaborate on the org's documents
    • 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
      • Org-wide policy rules (policies.read)
      • Replace the org-wide rules (admins)
      • A member's override and what applies to them
      • Replace a member's override (admins; managers for members)
      • Remove a member's 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 issued to a member (tokens.read)
      • Issue a managed fine-grained token (admins, billing)
      • Revoke a managed token (admins, billing)
    • Guides
      • Start here — Team app integration
      • Team API specification notes
      • Team socket specification notes
      • Team live socket — README
      • Team roles and access model
      • Team credentials and developer setup
      • Team SSO and portal workflows
      • Team policies, plans and seats
      • Team usage and collaboration insights
      • Team webhook delivery — README
  1. Membership

Add a person (managers)

POST
/api/v1/orgs/{id}/members
Team authority: Owner/admin can assign non-owner team roles; managers can add members only.
App integration: Adds the given user principal immediately without an acceptance step. Use only a principal the user has intentionally selected; use the invitation endpoint when you have an email. Seats and maximum team size (500) are enforced.

Request

Authorization
Bearer Token
Provide your bearer token in the
Authorization
header when making requests to protected resources.
Example:
Authorization: Bearer ********************
or
OAuth 2.0
Authorization Code
Add the parameter
Authorization
to Headers，whose value is to concatenate the Token after the Bearer.
Example:
Authorization: Bearer ********************
Authorize URL: https://handwrites.io/oauth/authorize
Token URL: https://handwrites.io/api/oauth/token
Refresh URL: https://handwrites.io/api/oauth/token
Scopes:
orgs:manage-Create, rename and delete teams and classrooms, manage members and invitations, join and leave
or
Path Params

Header Params

Body Params application/jsonRequired

Examples

Responses

🟢201
application/json
The membership.
Headers

Bodyapplication/json

🟠400BadRequest
🟠401Unauthorized
🟠403Forbidden
🟠404NotFound
🟠409Conflict
🟠422Unprocessable
🟠429TooManyRequests
🔴500ServerError
Request Request Example
Shell
JavaScript
Java
Swift
curl --location '/api/v1/orgs//members' \
--header 'Idempotency-Key;' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
    "principal": "string",
    "role": "owner"
}'
Response Response Example
201 - Example 1
{
    "principal": "user:3f2b…",
    "role": "owner",
    "email": "string",
    "addedBy": "user:3f2b…",
    "createdAt": "2019-08-24T14:15:22.123Z",
    "updatedAt": "2019-08-24T14:15:22.123Z"
}
Modified at 2026-10-26 13:12:30
Previous
Members (students see teachers and themselves)
Next
Change a role; owner transfers a team
Built with