Skip to main content
POST
Issue one grant per recipient under a single scope. Atomic across the batch.

Authorizations

X-API-Key
string
header
required

Headers

customer
string
required

Workspace identifier

Body

application/json
branch_id
string
required

Branch the grant unlocks. Use "master" for the base branch.

project_id
string
required

Project the grant is scoped to

recipients
object[]
required

Recipients of the grant. Each entry is an existing user_id, an existing user_group_id, or an email; emails for unknown users trigger an external-role invite.

starting_entity_id
string
required

Entity the view should anchor to for the recipient

view_id
string
required

CustomView.id from the project-scoped custom-views-2 registry

access_level
enum<string>
default:viewer

Capability granted for this scope. Viewer preserves v1 read-only sharing.

Available options:
viewer,
writer
branch_scope
enum<string>
default:branch

How far the grants reach from branch_id: that branch alone, it plus every branch descended from it, or every branch in the project.

Available options:
branch,
branch_and_children,
all_branches
expires_at
string | null

ISO8601 expiry. Omit for permanent grants.

suppress_notification
boolean
default:false

Response

201 - application/json
grants
object[]
required

Grants created — one per unique recipient.

invited_user_ids
string[]
required

Subset of recipient user ids whose User row was created by this call (i.e. the email was previously unknown).