Collaborators and Ownership Transfer

Use this guide to add team members to a handle, assign roles, and transfer ownership.

When to use

You need to give another user access to manage links, campaigns, or settings on your handle.
You need to hand over full ownership of a handle to a different user.
You want to review who has access and at what level.

Role hierarchy

Role	Can manage links, campaigns, analytics	Can manage webhooks, notifications, PATs	Can modify collaborators and transfer ownership
CREATOR	Yes	No	No
OPERATOR	Yes	Yes	No
OWNER	Yes	Yes	Yes

Every handle has exactly one OWNER. There is a maximum of 100 collaborators per handle.

UI path

Open https://app.{PUBLIC_DOMAIN}.
Navigate to your handle settings.
Open the Collaborators section.
Add a user by their user ID and assign a role (CREATOR, OPERATOR, or OWNER).
Save changes.

To transfer ownership, select a collaborator and promote them to OWNER. The previous owner is automatically demoted to OPERATOR.

Required auth

Owner-level JWT to modify collaborators or transfer ownership.
CREATOR-level JWT or above to view collaborators (read-only).

API fallback

List collaborators

GET /v2/handles/{handle}/collaborators

Response includes the owner user ID and an array of collaborator objects with userId and role.

Update collaborators

PUT /v2/handles/{handle}/collaborators

Send the full collaborators array. The owner is always preserved.

Request body:

{
  "collaborators": [
    { "userId": "user_abc", "role": "OPERATOR" },
    { "userId": "user_def", "role": "CREATOR" }
  ]
}

Transfer ownership

POST /v2/handles/{handle}/transfer-ownership

{
  "newOwnerUserId": "user_abc"
}

The new owner is promoted to OWNER. The previous owner is demoted to OPERATOR. All other collaborators keep their current roles.

Common errors

Code	Error	Cause
400	`invalid_collaborators`	Malformed collaborators array
400	`new_owner_required`	Missing `newOwnerUserId` in transfer request
403	`forbidden`	Caller is not the handle owner
404	`not_found`	Handle does not exist

Audit trail

Collaborator changes and ownership transfers are logged to the audit trail. View them with GET /v2/handles/{handle}/audit-events (OPERATOR role or above).