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 roles and access model

Team roles and access#

A team has one owner and the roles owner, admin, billing, manager, developer and member. The owner and admin share the admin permission tier, but deletion and transfer additionally require the actual owning principal. A role is not an API scope, and an API key's name does not confer a role.
ActionOwner/adminManagerBillingDeveloperMember
Read team and rosterYesYesYesYesYes
Read roster emailsYesYesYesNoNo
Rename teamYesNoNoNoNo
Add/invite/change membersNon-owner rolesMembers onlyNoNoNo
Create team-owned documentsYesYesNoNoNo
Access team-owned documentsOwner accessOwner accessViewEditEdit
Read stored team policiesYesYesYesYesNo
Change team-wide policyYesNoNoNoNo
Change a member overrideYesMember targets onlyNoNoNo
Read managed-member tokensYesYesYesNoNo
Issue/revoke managed-member tokensYesNoYesNoNo
Read team usageYesYes, document-onlyYesNoOwn usage only
Read collaboration insightsFull viewFull viewNoNoOwn share only
Configure billingYesNoYesNoNo
Configure SSOYesNoNoNoNo
Plan and policy checks may narrow every permitted action. The combined public member-policy view requires policies.read even for the caller's own override; ordinary members use /api/v1/me/policy for their own effective policy. Self-service removal is allowed for a non-owner. Changing a member to owner transfers the team and changes the previous owner to admin; it requires the actual owner, not just the admin tier.

Documents#

Team membership adds the team's principal to a person's authorization context. A team-owned document and a personal document shared to the team are different ownership cases. GET /api/v1/orgs/{id}/documents returns the former. For a document shared to the team, the grant's role also constrains access; billing remains viewer through the team grant.
A person may still have a direct grant independent of their team. Removing membership withdraws team-derived access, not every unrelated grant. Conversely, being a member does not entitle your app to every personal document the person owns. Honour a token's selected-document list.
For human members, current source allows only admin/manager tiers to create team-owned documents, even though developer/member roles can edit existing team-owned documents. New org-owned tokens use a separate principal-ownership path: a token whose own principal owns the document can have owner access even at user level. See credentials before applying this human-role table to a service token. Treat API refusals as authoritative rather than copying older product-plan tables.

Developer-tab controls#

New working-tree functionality adds an org-only developerAccess policy that controls who can create org-owned user-level tokens. Its values are everyone, managers, developers, admins, and off; the team default is developers. Only the admin tier can create admin-level org tokens. Billing never gains this token-creation capability. See credentials for per-request creator checks and the unverified release boundary.
Source: org-roles.ts, org-permissions.ts, orgs.ts, developer-access.ts, managed-tokens.ts, policies.ts, usage-org.ts, insights.ts.
Modified at 2026-10-26 13:24:10
Previous
Team live socket — README
Next
Team credentials and developer setup
Built with