Integrating a Partner

Overview

Integrators are applications and teams (internal or external) that connect to your EnSync integrations to publish and/or consume events. Each integrator is provisioned with unique credentials and scoped permissions to ensure least‑privilege access and clear operational boundaries.

EnSync supports a secure onboarding flow using an Integration Key to create a one‑time Integration Link ID that third‑party apps can redeem during onboarding.

Roles and responsibilities

Publishers create events that represent business actions (e.g., app/order/created, app/device/alert).
Consumers subscribe to topics to react to events (e.g., app/fulfillment, app/analytics, app/notifications).
A partner (integrator) act as both publisher and consumer in different workflows.

Identity and access

Partner embedded URL returned by the API for the external app to complete onboarding and manage events/secrets.
Unique keys per integrator and per environment (dev/stage/prod) after onboarding.
Granular send/receive permissions by topic/event.
Key rotation policies and audit trails.

Authentication

Use the Integration Key you got when you created an integration page from the EnSync Dashboard as a Bearer token in the Authorization header when creating a partner embedded link:

Authorization: Bearer <integration-key>

Onboarding via API (create an integration link)

Create a one‑time integration link that an external application can use to integrate with your workspace.

Path: /api/v1/external/partner
Method: POST
Auth: Bearer <integration-key>
Headers:
- Content-Type: application/json
- Authorization: Bearer <integration-key>
Allowed body fields only (others are rejected):
- appName (string, optional)
- appDescription (string, optional)
- metadata (object, optional)

Example:

curl -X POST 'https://api.ensync.cloud/api/v1/external/partner' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <integration-key>' \
  --data-raw '{
    "appName": "Paydantic",
    "appDescription": "Contract like a pro",
    "metadata": { "id": "123456789" }
  }'

Successful response:

{
    "success": true,
    "message": "Partner created successfully",
    "data": { "id": "<partner-id>", "url": "<partner-embeded-url>" }
}

Notes:

data.id is the partner's id used by you to identify the partner (integrator).
data.url is the partner's embedded URL used by your app to enable the partner onboard, manage events, and manage secrets on your app.

Metadata and presentation

Optional app metadata (name, description, color, icon) to identify integrators in UIs.
Tags and custom metadata for ownership, SLA, and support routing.

Lifecycle

Request access or invitation to an integration.
Receive keys and permissions aligned to your role.
Implement event publishing/subscribing with SDKs.
Validate in lower environments; promote to production.
Monitor performance and errors; maintain keys and versions.

EnSync Engine Documentation Help