The Bucket Permission trigger runs workflows when a user is granted permissions to a bucket. This typically happens when a user accepts a bucket invitation. Use it for welcome workflows, onboarding notifications, or syncing access when someone joins a bucket.
Trigger Type
bucket_permissionWhen It Fires
The trigger fires when a permission record is created for a user on a bucket (e.g. read, write, or admin). You can filter by:
- Bucket ID — Only trigger for a specific bucket; leave empty for any bucket.
- Permission Type — Only trigger for a specific level: read, write, or admin; leave empty for any.
- Public Trigger — When enabled, the workflow triggers for any bucket permission creation (platform-wide), not just permissions in your buckets. Requires the workflow to be deployed.
- Cooldown (minutes) — Minimum time between triggers for the same user/bucket combination (0 = no cooldown).
- Trigger Once Per User/Bucket — Only trigger once per user/bucket (useful for welcome workflows).
Outputs (Reference in Downstream Blocks)
Use <block_id.output_name> to pass trigger data to the next blocks.
| Output | Type | Description |
|---|---|---|
eventId | string | Unique ID of the triggering event |
eventType | string | Permission event type (e.g. permission_created) |
triggeredAt | string | ISO timestamp when trigger fired |
permissionId | string | ID of the created permission record |
userId | string | ID of user who received the permission |
userEmail | string | Email of user who received the permission |
username | string | Username of user who received the permission |
bucketId | string | ID of the bucket |
bucketName | string | Name of the bucket |
permissionType | string | Type of permission granted (read, write, admin) |
createdAt | string | ISO timestamp when permission was created |
viaInvitation | boolean | Whether this permission was created via invitation acceptance |
invitationId | string | ID of the invitation (if created via invitation) |
Common Use Cases
Welcome workflow when someone joins a bucket
- Add the Bucket Permission trigger (leave bucket empty or set a specific bucket).
- Optionally enable Trigger Once Per User/Bucket so each user gets one welcome.
- In the next block (e.g. send notification or add to a list), use
<bucket_permission_1.userId>and<bucket_permission_1.bucketName>to personalize the message.
Notify only for admin permissions
Set Permission Type to Admin so the workflow runs only when a user is granted admin access to a bucket.
Sync or log permission changes
Use Public Trigger to run a workflow for any bucket permission creation across the workspace. Reference userId, bucketId, and permissionType to sync to an external system or log access.
Referencing Trigger Outputs
# Send welcome message to the user who got access
userId: "<bucket_permission_1.userId>"
bucketName: "<bucket_permission_1.bucketName>"For triggers, use <block_id.outputName> syntax. The workflow runs in the context of the user who received the permission when the trigger is not public; with Public Trigger, ensure your workflow uses the trigger outputs to identify the user and bucket.