EnSync uses a four-layer delivery model to control event access. For an event to be delivered, all four conditions must align.
Permissions (What You CAN Access)
Permissions define which events an app is allowed to publish or receive. Set by the event owner.
- Publish Permission: Can this app publish this event type?
- Receive Permission: Can this app subscribe to this event type?
Permissions are configured in the EnSync Dashboard or via the Config Manager API.
Subscriptions (What You WANT to Receive)
Subscriptions define which events an app actively wants to receive. Managed by the app owner via SDK.
// Subscribe to an event type
await client.subscribe('order.created', async (event) => {
console.log('Received order:', event.data);
});
How Validation Works
When Publishing
- EnSync validates the publisher has permission to publish that event
- If valid, event is sent to specified Client IDs
- If invalid, publish is rejected
// You must have permission to publish 'order.created'
await client.publish('order.created', orderData, ['partner_client_id']);
When Subscribing
- EnSync validates the subscriber has permission to receive that event
- If valid, subscription succeeds
- If invalid, subscription fails immediately
// Subscription only succeeds if you have receive permission
await client.subscribe('order.created', handler);
// ✅ Success: You have permission
// ❌ Error: Permission denied
When Delivering
Events are only delivered when all four conditions are met:
- Permission (platform sets): You have receive permission for that event type
- Subscription (you set): You have an active subscription to that event type
- Event name matching (automatic): Published event type matches your subscription pattern
- Recipient targeting (platform sets per-event): Event is explicitly addressed to your Client ID
Subscriptions act as filters: Events addressed to you but outside your subscriptions will queue based on your plan’s retention period (up to 30 days). Subscribe later to automatically receive queued events.
Targeted Delivery Example
// Partner A has permission + subscription to 'order.created'
await partnerA.subscribe('order.created', handler);
// You publish to Partner A's Client ID
await client.publish('order.created', data, ['partner_a_client_id']);
// ✅ Partner A receives it
// You publish to Partner B's Client ID
await client.publish('order.created', data, ['partner_b_client_id']);
// ❌ Partner A does NOT receive it (not addressed to them)
Even if you’re subscribed to an event type, you only receive events explicitly addressed to your Client ID. This ensures multi-tenant data isolation.
The Four Layers Explained
| Layer | Who Controls | Purpose |
|---|
| Permission | Event owner | What you CAN access |
| Subscription | App owner | What you WANT to receive (acts as filter) |
| Event Name | Automatic | Matches published event to subscriptions |
| Recipient Targeting | Publisher (per-event) | Who should receive this specific event |
Permission vs Subscription
| Aspect | Permission | Subscription |
|---|
| Who sets it | Event owner | App owner |
| Controls | What you CAN access | What you WANT to receive |
| Scope | Event type level | Event type level |
| Validation | At publish/subscribe time | At subscribe time |
| Can change | Via Dashboard/API | Via SDK |
Managing Permissions
Via Integration Page
Partners can manage their subscriptions within the permissions you’ve granted:
- View available events (based on your permission grants)
- Subscribe to events they want to receive
- Unsubscribe from events they no longer need
- View event metrics and analytics
Via Config Manager API
You can programmatically manage permissions:
Best Practices
- Grant minimum permissions - Only give access to events partners need
- Let partners manage subscriptions - They know which events they want
- Review permissions regularly - Remove access when partnerships end
- Use integration pages - Enable partners to self-manage their subscriptions
