1. Guides
Handwrite Team
  • Handwrite Regular Accounts
    • Schemas
      • Error
      • Principal
      • Role
      • Access
      • ContentType
      • Language
      • FileRef
      • Document
      • Tombstone
      • DocumentPage
      • CreateDocument
      • UpdateDocument
      • FileInfo
      • CommitUpload
      • Upload
      • DownloadLink
      • Extracted
      • ExtractionFailed
      • CommittedDocument
      • ExtractedDocument
      • SearchHit
      • SearchPage
      • Export
      • Permission
      • Share
      • ChangeRole
      • Invitation
      • Permissions
      • ReceivedInvitation
      • AcceptedInvitation
      • Me
      • WebhookEventType
      • Webhook
      • CreateWebhook
      • CreatedWebhook
      • WebhookDelivery
      • AudioFormat
      • Speech
      • WordTiming
      • SpeechMarks
      • AudioLink
      • Voice
      • Quota
      • SettingEntry
      • Settings
      • SettingsPatch
      • PatchedSettings
      • OAuthToken
      • OAuthError
  • 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
      • Join with the invited role
      • Decline an organisation invitation
      • Members (students see teachers and themselves)
      • Add a person (managers)
      • Change a role; owner transfers a team
      • Remove a member (managers) or yourself
      • Leave (not the owner)
      • Pending email invitations (managers)
      • Invite an email (managers)
      • Withdraw an invitation (managers)
    • 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
    • Schemas
      • Error
      • Principal
      • Access
      • ContentType
      • Language
      • FileRef
      • Document
      • Tombstone
      • DocumentPage
      • OrgKind
      • OrgRole
      • Organisation
      • CreateOrganisation
      • RenameOrganisation
      • Member
      • AddMember
      • ChangeMember
      • InviteMember
      • OrgInvitation
      • ReceivedOrgInvitation
  • Handwrite Classroom
    • Schemas
      • Error
      • Principal
      • Access
      • ContentType
      • Language
      • FileRef
      • Document
      • Tombstone
      • DocumentPage
      • OrgKind
      • OrgRole
      • Organisation
      • CreateOrganisation
      • RenameOrganisation
      • Member
      • AddMember
      • ChangeMember
      • InviteMember
      • OrgInvitation
      • ReceivedOrgInvitation
  1. Guides

Start here — Team app integration

Handwrite Team for outside developers#

Build a team document library, shared editing experience, membership tool, or permitted usage dashboard. A Handwrite team has a team:org_… principal, while each person keeps a user:… identity. Connecting a person is not the same as granting your app authority over their team.
This edition documents the 30 shared /api/v1/orgs operations in a team context. The routes also serve classes: create with kind: "team", check returned kind, and let the user deliberately choose the team. The personal document, file, speech, settings and OAuth APIs are described in Regular Accounts.

Connect an app#

1.
For an app used by several people, use Handwrite OAuth authorization code with PKCE and request only required scopes. A private server integration can use a securely stored user API key. See credentials and developer setup.
2.
Check GET /api/v1/me, then list GET /api/v1/orgs with orgs:read. Match the returned identity to the connected account.
3.
Show teams the caller belongs to and their current role. Let the person choose a team and documents; connection must not silently import every team library.
4.
Use the chosen team ID for organisation calls. A scope permits a type of API operation; membership, role, plan, effective policy and document restrictions still decide access.
5.
Clear team-specific caches and re-evaluate connected features after membership, policy or credential changes. Show refusals as actionable states rather than silently requesting broader access.
curl --fail-with-body https://handwrites.io/api/v1/me \
  -H "Authorization: Bearer $HANDWRITE_ACCESS_TOKEN"

curl --fail-with-body https://handwrites.io/api/v1/orgs \
  -H "Authorization: Bearer $HANDWRITE_ACCESS_TOKEN"

curl --fail-with-body 'https://handwrites.io/api/v1/orgs/REPLACE_TEAM_ID/documents?limit=20' \
  -H "Authorization: Bearer $HANDWRITE_ACCESS_TOKEN"
Use a backend for browser integrations: authenticated REST routes do not provide a general cross-origin browser CORS interface. Do not distribute a personal key in a web bundle or mobile app. Public OAuth clients use PKCE without a client secret; confidential clients keep their secrets on the server.

Read before implementing#

API specification notes: headers, request bodies, errors, pagination and retries.
Roles and access: who may act and how document ownership differs from membership.
Credentials and developer setup: personal, managed-member and org-owned tokens.
Policies, plans and seats: effective restrictions and capacity failures.
SSO and portal workflows: what users configure through Handwrite rather than an external API.
Socket specification notes and socket README: live document co-editing.
Usage and collaboration insights: counters, redaction and polling.
Webhook delivery README: receiving document and organisation events.
Each reference operation has its own README with a request example, authority checks and response handling. Use a dedicated test account and disposable team for write tests. The isolated app-testing identity only checks /me and /voices; it has no team access.

Verification boundary#

The 30-operation contract derives from the OpenAPI snapshot checked against the live public spec on 2026-10-26. Source code adds implementation details; it is not proof of a successful authenticated deployment flow. New Developer-tab org credentials, staff API suspension and organisation webhook changes are present in the current working tree and their release was not verified. Team portal DNS/CloudFront aliases were absent in the provider snapshot taken during this documentation task. Treat setup guidance as a capability description, not an assertion that the separate portal is reachable.
Modified at 2026-10-26 13:21:46
Previous
Revoke a managed token (admins, billing)
Next
Team API specification notes
Built with