Change someone's role (owner)

PATCH

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

App integration: Owner-only: encode the complete principal in the URL. Updating a document role changes that recipient's access, not their account role or token scopes. Reflect the returned permission in your access panel.

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

Body Params application/jsonRequired

Examples

Responses

🟢200

application/json

The permission.

Headers

Bodyapplication/json

🟠400BadRequest

🟠401Unauthorized

🟠403Forbidden

🟠404NotFound

🟠429TooManyRequests

🔴500ServerError

Request Example

Shell

JavaScript

Java

Swift

curl --location --request PATCH '/api/v1/documents//permissions/' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
    "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 12:58:15

Share by principal, or invite by email (owner)

Remove access (owner, or leave yourself)