Share by principal, or invite by email (owner)

POST

/api/v1/documents/{id}/permissions

App integration: Owner-only: send either a principal or an email plus viewer/editor role. Principal sharing returns 200/201; email always returns 202 pending invitation, irrespective of account existence. Do not tell the user an email invitation granted immediate access. The current implementation does not send invitation email. The invitee must sign in with the matching verified address and open their Handwrite invitation inbox.

Request

Authorization

Bearer Token

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

OAuth 2.0

Authorization Code

Add the parameter

Authorization

to Headers，whose value is to concatenate the Token after the Bearer.

Example:

Authorization: Bearer ********************

Authorize URL: https://handwrites.io/oauth/authorize

Token URL: https://handwrites.io/api/oauth/token

Refresh URL: https://handwrites.io/api/oauth/token

Scopes:

permissions:write-Share documents and change or remove access

Path Params

Header Params

Body Params application/jsonRequired

Examples

Responses

🟢200

application/json

A principal's role was changed.

Headers

Bodyapplication/json

🟢201

🟢202

🟠400BadRequest

🟠401Unauthorized

🟠403Forbidden

🟠404NotFound

🟠409Conflict

🟠422Unprocessable

🟠429TooManyRequests

🔴500ServerError

Request Example

Shell

JavaScript

Java

Swift

curl --location '/api/v1/documents//permissions' \
--header 'Idempotency-Key;' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "email": "user@example.com",
    "role": "viewer"
}'

Response Example

200 - Example 1

{
    "principal": "user:3f2b…",
    "role": "viewer",
    "email": "string",
    "grantedBy": "user:3f2b…",
    "createdAt": "2019-08-24T14:15:22.123Z",
    "updatedAt": "2019-08-24T14:15:22.123Z"
}

Modified at 2026-10-26 13:23:39

Who a document is shared with

Change someone's role (owner)