Share a file

Grants another person access. Requires files.share, which is separate from files.write.

POST /v1/files/:id/permissions

Permission

The key must be granted files.share

A key without it gets 403 insufficient_scope, with the missing permission named in details.

Needs files.share, which is separate from files.write for the reason the taxonomy gives: sharing changes who else can see data, and a key granted enough to organise a drive should not thereby be able to expose it.

Path parameters

Field	Type	Description
`id` required	string	The file or document to share.

Request body

Field	Type	Description
`principal_id` required	string	Who to share with: a user id, or a group id when principal_type says group.
`role` required	string	What they may do with it.
`principal_type`	string	user or group. Defaults to `user`

Request

curl https://api.veruapis.com/v1/files/:id/permissions \
  -X POST \
  -H "Authorization: Bearer vak_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "principal_id": "01918e4b-9999-7f11-b4a9-0242ac130003", "principal_type": "user", "role": "editor" }'

Idempotency-Key is required on every write. Retrying with the same key returns the original response rather than repeating the operation, so a timeout is something you retry rather than something you investigate.

Response

Answers 201.

Field	Type	Description
`id`	string	Pass it back to revoke this grant.
`principal_type`	string	`usergroup`
`principal_id`	string
`role`	string	What the grant allows.
`created_by`	string	Who shared it.
`created_at`	RFC 3339

{
  "data": { "id": "0192c001-0000-7a41-b8d2-5e9f0c3a7b41", "principal_type": "user", "principal_id": "01918e4b-9999-7f11-b4a9-0242ac130003", "role": "editor", "created_by": "01918e4b-7c2e-7f11-b4a9-0242ac130003", "created_at": "2026-09-02T11:00:00Z" },
  "meta": { "request_id": "req_01j8z9...", "timestamp": "2026-09-02T10:00:00Z" }
}

Worth knowing

A person is named by their workspace user id, not their email — resolve one through /v1/users. Needs files.share, which is separate from files.write on purpose: organising a drive and exposing it are different risks.

Errors

Every failure uses the same shape, with a stable string code you can branch on. See the error reference.

POST `/v1/files/:id/permissions`

Your API key Used once, never stored.

id

principal_id principal_type role