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 credentials and developer setup

Choose the principal your integration needs to act as. Sharing a token does not create a new identity, and none of these API credentials is an interactive account sign-in password.
CredentialActs asIntended useKey limits
Personal API keyIts userPrivate integration owned by that personScopes, fine-grained levels, selected documents, membership and policy apply.
OAuth access tokenConsenting userAn app connected by multiple peopleRequest minimum scopes; use authorization code with PKCE. A revoked consent or changed policy ends access.
Managed-member tokenThe selected user, with managing team recordedTeam-controlled access for a memberFine-grained, 1–30 days; member-tier holders only; cannot contain orgs:manage.
Org-owned tokenteam:org_…New Developer-tab service integrationWorking-tree feature; release unverified. User/admin levels, 1–30 days, creator standing rechecked on each request.
Isolated app-test identityapp:…Operator deployment verification onlyOnly /me and /voices. No users, documents, memberships or teams.

Personal integrations and OAuth#

Use account developer controls for a private API key. For a distributed app, use the Regular Accounts OAuth guidance. Each user connects their own account; never distribute your own key. Keep refresh operations serialized and atomically save replacement refresh tokens. Revocation and token expiry are expected reconnect states, not reasons to fall back to a more privileged credential.

Managed-member tokens#

Owners/admins and billing can call POST /api/v1/orgs/{id}/members/{principal}/tokens when the plan permits managed tokens. Managers can list these tokens but cannot issue/revoke them. The target must be a regular member; admins, managers, developers and billing are not valid holders.
The response reveals secret once. Store it through the intended secure recipient workflow. Subsequent listings contain summaries only. Fine-grained permission levels and chosen document IDs narrow its use. documents: "all" means all documents otherwise accessible to that user, not unrestricted access to every account. Managed tokens cannot request orgs:manage.
The managing team revokes the credential. Promotion out of member tier revokes existing managed tokens; membership removal also ends managed access. The holder cannot override managedBy through personal developer controls.

Org-owned tokens — current source, release unverified#

The working tree implements a team Developer tab. This setup uses Handwrite's authenticated portal, not a new documented public /v1 creation endpoint. An org token is owned by team:org_…, and is different from a managed token owned by user:….
User level can request document permissions through delete, sharing through write, and organisation read. It uses member-tier standing for organisation administration; this is not a member-level cap on documents owned by the token's own organisation principal.
Admin level adds organisation management and acts at admin tier. Only an owner/admin may create it.
No audio, voices or webhook-management scopes are available to these tokens. They cannot create organisations, accept a person's invitations, join live rooms or replace OAuth consent for a person.
Each request rechecks the team, plan, developerAccess and the creator's current membership. Leaving or losing permitted standing refuses the token; an admin demotion can reduce an admin token to user level. off refuses existing org tokens.
Admins can inspect/revoke all org tokens. Other permitted creators see only their own. Do not assume staff API suspension revokes these new tokens: their current authentication path omits the common staff-block gate. Token revocation and developerAccess: off are separate controls; verify the released behavior before relying on a complete API stop.
For individual-document operations, current source grants owner access when the document's owner equals the token's team: principal. With the corresponding scopes and policy permission, even a user-level org token can therefore create, edit, share or delete that organisation's documents; a token limited to selected documents cannot create new ones. It does not become the team's human owner for organisation deletion or ownership transfer. The organisation-listing access field is calculated from the token's member/admin role and can differ from this individual-document ownership check. Treat org-owned tokens as service credentials with potentially broad document authority, not as a substitute for a member's narrowly scoped key.
Source: api-keys.ts, http.ts, policy-schemas.ts, managed-tokens.ts, developer.ts, developer-access.ts. The org-token section documents current source semantics and must be verified against the released service before adopting it.
Modified at 2026-10-26 13:24:10
Previous
Team roles and access model
Next
Team SSO and portal workflows
Built with