Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.ensync.cloud/llms.txt

Use this file to discover all available pages before exploring further.

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

  1. EnSync validates the publisher has permission to publish that event
  2. If valid, event is sent to specified Client IDs
  3. If invalid, publish is rejected
// You must have permission to publish 'order.created'
await client.publish('order.created', orderData, ['partner_client_id']);

​
When Subscribing

  1. EnSync validates the subscriber has permission to receive that event
  2. If valid, subscription succeeds
  3. 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:
  1. Permission (platform sets): You have receive permission for that event type
  2. Subscription (you set): You have an active subscription to that event type
  3. Event name matching (automatic): Published event type matches your subscription pattern
  4. 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

LayerWho ControlsPurpose
PermissionEvent ownerWhat you CAN access
SubscriptionApp ownerWhat you WANT to receive (acts as filter)
Event NameAutomaticMatches published event to subscriptions
Recipient TargetingPublisher (per-event)Who should receive this specific event

​
Permission vs Subscription

AspectPermissionSubscription
Who sets itEvent ownerApp owner
ControlsWhat you CAN accessWhat you WANT to receive
ScopeEvent type levelEvent type level
ValidationAt publish/subscribe timeAt subscribe time
Can changeVia Dashboard/APIVia SDK

​
Managing Permissions

​
Via Integration Page

Partners can manage their subscriptions within the permissions you’ve granted:
  1. View available events (based on your permission grants)
  2. Subscribe to events they want to receive
  3. Unsubscribe from events they no longer need
  4. View event metrics and analytics

​
Via Config Manager API

You can programmatically manage permissions:

​
Best Practices

  1. Grant minimum permissions - Only give access to events partners need
  2. Let partners manage subscriptions - They know which events they want
  3. Review permissions regularly - Remove access when partnerships end
  4. Use integration pages - Enable partners to self-manage their subscriptions