Thread authentication
The thread authenticator enforces ownership rules for threads and comments in collaborative documents. When enabled, users can only edit and delete their own threads and comments, while thread creation automatically assigns the authenticated user's ID.
Requires JWT authentication
Thread authentication relies on JWT authentication to identify users. Make sure your JWTs include the sub claim with a unique user identifier.
Enable thread authentication
Enable the thread authenticator by setting the thread_authenticator setting to 1 via the Settings API:
curl --location --request PUT 'https://YOUR_APP_ID.collab.tiptap.cloud/api/admin/settings/thread_authenticator' \
--header 'Authorization: YOUR_SECRET_FROM_SETTINGS_AREA' \
--header 'Content-Type: text/plain' \
-d '1'You can also set the COLLAB_THREAD_AUTHENTICATOR environment variable to 1 on self-hosted instances.
How it works
When enabled, the thread authenticator intercepts all document updates that modify threads or comments and validates them against the authenticated user's identity.
Automatic user ID assignment
When a user creates a thread or comment, the authenticator automatically assigns their user ID (from the JWT sub claim) to the thread and comment. This happens transparently and does not require any client-side changes.
Ownership enforcement
The following rules are enforced for all thread and comment operations:
| Operation | Rule |
|---|---|
| Create thread | Allowed. The authenticated user's ID is assigned automatically. |
| Edit thread | Only the thread owner can edit. |
| Delete thread | Only the thread owner can delete. |
| Resolve/unresolve thread | Owners can always resolve. Non-owners depend on access level (see below). |
| Create comment | Allowed. The authenticated user's ID is assigned automatically. |
| Edit comment | Only the comment owner can edit. |
| Delete comment | Only the comment owner can delete. |
If a user attempts an unauthorized action, the server rejects the update and returns an unauthorized error.
Threads without a user ID
Threads and comments that were created before enabling the thread authenticator may not have a user ID assigned. These can be edited or deleted by anyone. Once a user modifies such a thread, their user ID is assigned to it.
Resolving foreign threads
By default, all users with write or comment access can resolve threads they don't own. This is useful for workflows where reviewers or editors need to mark discussions as resolved.
To restrict comment-only users from resolving other users' threads, set the commentonly_disallow_resolve_foreign_threads setting to 1:
curl --location --request PUT 'https://YOUR_APP_ID.collab.tiptap.cloud/api/admin/settings/commentonly_disallow_resolve_foreign_threads' \
--header 'Authorization: YOUR_SECRET_FROM_SETTINGS_AREA' \
--header 'Content-Type: text/plain' \
-d '1'The resulting permission matrix for resolving foreign threads:
| Access level | Default behavior | With commentonly_disallow_resolve_foreign_threads set to 1 |
|---|---|---|
| Write access | Can resolve | Can resolve |
| Comment-only access | Can resolve | Cannot resolve |
Thread owners can always resolve their own threads regardless of this setting.
Configuration reference
| Setting | Environment variable | Default | Description |
|---|---|---|---|
thread_authenticator | COLLAB_THREAD_AUTHENTICATOR | 0 (disabled) | Set to 1 to enable thread authentication. |
commentonly_disallow_resolve_foreign_threads | COLLAB_COMMENTONLY_DISALLOW_RESOLVE_FOREIGN_THREADS | 0 (allowed) | Set to 1 to prevent comment-only users from resolving threads they don't own. |
Both settings can be configured via the Settings API or environment variables.