1. Guides
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
      • 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
  1. Guides

Team SSO and portal workflows

Team SSO signs people into Handwrite. It does not grant a third-party app team-wide API access. A signed-in person still connects your integration through the supported credential/consent flow.

What the team administrator configures#

The current implementation supports one SAML 2.0 or OpenID Connect provider per Team Plus team, with verified work-email domains. The administrator uses Handwrite's SSO settings to receive the correct federation URLs, add domain verification records and configure the provider. The source permits at most 50 domains, each at most 40 characters, and rejects unsuitable public-email or local domains.
The lookup flow chooses SSO or password by email domain without returning a team name. A first successful SSO sign-in joins the person as a member, subject to a seat check. A conflicting existing password-account email is not automatically linked. SSO in the native iOS app is not implemented by this flow; do not offer it there based only on the web capability.
Removing SSO is a membership-preserving conversion workflow: users are moved to password identities, receive the password setup flow, and retain transferred team/document relationships. Third-party app authorizations do not transfer as if they were fresh consent; integrations must handle reconnecting. This behavior is source-derived and must be tested during a real provider rollout.

Public API versus the portal#

WorkflowSupported surface
List/create team, membership, invitations, policies, managed-member tokens, usageThe documented /api/v1/orgs API with appropriate credentials.
Purchase/cancel plan or change paid seatsHandwrite Billing tab.
Configure SSO, domains and providerHandwrite SSO settings.
View staff/team audit and perform product-specific export controlsThe authorized Handwrite console.
Create org-owned tokens and register org webhook receiversCurrent Developer-tab implementation; release must be verified.
Private cookie-session /api/org and SSO callback routes support the Handwrite UI and are not presented here as stable bearer-key APIs. Do not scrape session cookies, emulate the login callback or send a personal key to those routes. No SCIM provisioning endpoint was found in the current implementation; do not promise SCIM support.

Deployment boundary#

At the documentation snapshot on 2026-10-26, Team portal DNS and CloudFront aliases were not present in the read-only provider check. No real identity-provider sign-in or invitation-email delivery was verified here. The internal deployment/SSO runbooks contain operator setup details; this developer guide describes the intended user workflow without treating configuration as a completed rollout.
Source: TEAMS_SSO.md, sso.ts, sso-schemas.ts, src/app/api/auth/sso/**, src/app/api/org/** and the portal pages.
Modified at 2026-10-26 13:13:45
Previous
Team credentials and developer setup
Next
Team policies, plans and seats
Built with