# Understanding the Synqly Model

Synqly solves the operational complexity of building and maintaining integrations across many
services while keeping a consistent, unified developer experience.

Instead of writing custom
code for every provider, your application integrates **once** with Synqly's unified APIs.  Synqly handles translation, normalization, and provider-specific
execution behind the scenes.

synqly data flow
Internally, Synqly introduces organizational, integration, and security models that ensure tenant
isolation, secure authentication, and scalable integration management. Those models are the real
foundation of the platform and understanding them makes everything else click.

## Platform Overview

The Synqly platform is built around three connected layers. Each exists to solve a distinct
architectural problem.

Organizational Model
**Who owns what.** Defines ownership, access control, and how customer data stays isolated
across your entire deployment.

Integration Model
**How things connect.** Defines how external systems are wired up, configured, and made
reusable across tenants.

Authentication Model
**How access is controlled.** Separates administrative authority from runtime execution
using distinct token scopes.

## Organizational Model

**Who owns what.** Defines ownership, access control, and how customer data stays isolated across your entire deployment.


```mermaid
flowchart TD
    org(Organization)
    mem(Members)
    ips(Integration Points)
    acc(Accounts)
    int(Integrations)
    eu(End Users)
    ten(Your Tenants)

    org --> mem & ips & acc
    acc --> int
    ten -.->|"represented by"| acc
    eu -.->|"belong to"| ten
```

At the root of this model is the **Organization**, which owns the resources required to operate an integration ecosystem, including **Members**, **Integration Points**, and **Accounts**. Accounts typically represent your customers or tenants, providing isolated environments where integrations can be configured and managed independently.

Understanding the Organizational Model is essential for understanding how Synqly approaches multi-tenancy, security, and resource ownership.

The following sections explore each concept in greater detail and explain how they work together to establish ownership boundaries.

Organization
The root container that owns all Synqly resources and establishes the governance boundary.

Members
Personal accounts and service accounts that act within an Organization.

Accounts
Synqly's representation of your customers, providing strict data isolation between tenants.

End Users
The customers of your customers who authenticate providers or configure connections.

## Integration Model

**How things connect.** Defines how external systems are wired up, configured, and made reusable across your tenants.


```mermaid
flowchart LR
    conn(Connector - Ticketing)
    ip(Integration Point)
    int(Integration)
    prov1(Provider - Jira)
    prov2(Provider - ServiceNow)
    prov3(Provider - Zendesk)
    conn -->|"unified interface"| ip
    ip -->|"policy + config"| int
    int --> prov1 & prov2 & prov3
```

At a high level, the model separates:

- What your application integrates with (Connector)
- How that integration is governed (Integration Point)
- Which provider is actually connected (Integration)


This separation allows applications to integrate against a stable, unified interface while retaining the flexibility to connect different providers for different customers or environments.

The following sections explain each component of the Integration Model in detail. Start with the concept you're interested in, or read them in order to understand how integrations are built from the unified interface down to the provider connection

Connectors
A unified API and data model abstracting a category of providers, such as Ticketing or Identity.

Integration Points
Reusable governance rules defined once at the Organization level and applied across many Integrations.

Integrations
The live, authorized connection between an Account and a specific Provider.

Providers
Specific third-party platforms — Jira, Okta, Slack, AWS — that Connectors expose.

## Authentication Model

**How access is controlled.** Separates administrative authority from runtime execution using distinct token scopes.

Synqly exposes two distinct API layers, and each requires a different kind of credential.

The **Management APIs** control how your integration system is structured — creating Accounts, configuring Integration Points, managing Members. The **Connector APIs** perform the actual work against external providers — fetching tickets, querying identity events, routing alerts.

These two layers carry fundamentally different levels of authority, and Synqly enforces that separation by design.

| Token | API layer | Authority |
|  --- | --- | --- |
| **Organization Access Token** | Management APIs | Broad — operates across the entire Organization |
| **Integration Access Token** | Connector APIs | Narrow — scoped to a single Integration |


This separation is enforced at the platform level, not just by convention. A runtime Integration Access Token cannot perform administrative operations, and an Organization Access Token cannot call Connector APIs. Each token is strictly limited to the layer it was issued for. The result is least-privilege by default.

Organization Access Tokens
Credentials for the Management APIs — used for administrative operations across an Organization.

Integration Access Tokens
Credentials for the Connector APIs — scoped to a single Integration for runtime provider access.

## Putting It All Together

The complete Synqly model, from organizational structure through to runtime execution:


```mermaid
flowchart TD
    org(Organization)
    mem(Members)
    ips(Integration Points)
    acc(Account)
    int(Integration)
    prov(Provider)

    org --> mem & ips & acc
    acc --> int --> prov
```

The typical integration lifecycle follows this sequence:

1. **Authenticate** using an Organization Access Token
2. **Create** an Account to represent a tenant in your system.
3. **Configure** an Integration within that Account, referencing a Provider
4. **Generate** an Integration Access Token scoped to that Integration
5. **Call** Connector APIs using the Integration Access Token to interact with the Provider



```mermaid
flowchart TD
    product("Your Product")
    mgmt("Management APIs")
    conn("Connector APIs")
    accounts("Create Accounts & Integrations")
    providers("Interact with Providers")

    product -- "Organization Access Token" --> mgmt
    product -- "Integration Access Token" --> conn
    mgmt --> accounts
    conn --> providers
```