1. Managed tokens
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)
        GET
      • Issue a managed fine-grained token (admins, billing)
        POST
      • Revoke a managed token (admins, billing)
        DELETE
    • 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. Managed tokens

README — POST /api/v1/orgs/{id}/members/{principal}/tokens

Issue a managed fine-grained token (admins, billing)#

POST /api/v1/orgs/{id}/members/{principal}/tokens · Operation ID: issueManagedToken

App purpose#

Creates a member-owned fine-grained credential valid for 1–30 days. It acts as the member, not the team. It cannot contain orgs:manage. Store the one-time secret securely and deliver it only through your authorised flow; do not put it in logs or ordinary messages.

Authentication and authority#

Bearer credential with orgs:manage. Owner/admin or billing (tokens.manage), plan with managedTokens, target must be member tier.
Scopes do not replace role, ownership, plan, current membership or effective-policy checks. The team edition uses the shared organisation route with a team ID; it does not change the backend schema for classes.

Example#

Replace all REPLACE_* values and use an authorised disposable team for tests. Read-only examples still require the appropriate data access. Mutating examples change team state; policy PUT examples are complete replacements.
curl --fail-with-body -X POST 'https://handwrites.io/api/v1/orgs/REPLACE_TEAM_ID/members/user%3AREPLACE_USER_ID/tokens' \
  -H "Authorization: Bearer $HANDWRITE_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"name":"Document reader","permissions":{"documents":"read"},"documents":["doc_REPLACE_DOC_ID00"],"expiresInDays":7}'

Parameters#

NameInRequiredMeaning
idpathYesAn organisation ID (org_…).
principalpathYesA principal, URL-encoded (user%3A…).

Request body#

application/json (required).
FieldRequiredShape
nameYesstring
permissionsYesobject
documentsNoSee reference schema
expiresInDaysYesinteger

Responses and recovery#

StatusMeaningFormat
201The token and its secret.application/json
400invalid_request (the message names the field), validation_failed.application/json
401unauthorized: no token, or it's invalid, revoked or expired.application/json
403insufficient_scope, forbidden (you can see it but not do this), app_test_restricted, account_deleted (the account is scheduled for deletion; any request).application/json
404not_found: it doesn't exist or you can't see it (never 403 for documents you can't see).application/json
422limit_reached, idempotency_mismatch, unreadable_file, no_text, empty_document.application/json
429rate_limited (burst or daily cap) or quota_exceeded (no characters left).application/json
500internal_error.application/json
Treat 403 as a current authority/policy failure and 404 as unavailable to this caller, without probing other accounts. Plan and seat checks may add 402 failures beyond generic reference responses. Retry only when the operation semantics permit it; keep Request-Id for support. Do not parse a 204 or 304 as JSON.
Read Team API specification notes, roles and access, and credential boundaries for the shared rules.
Modified at 2026-10-26 13:21:46
Previous
README — GET /api/v1/orgs/{id}/members/{principal}/tokens
Next
README — DELETE /api/v1/orgs/{id}/members/{principal}/tokens/{tokenId}
Built with