Connectors and Applications

Orchesty splits "talking to a third-party service" into two parts:

  • An Application represents the service (Hubspot, Shopify, your internal ERP). It declares how to authenticate, what settings the service needs (API key, base URL, scopes), and exposes that as a configuration form.
  • A Connector represents one HTTP call to the service (HubspotListContacts, HubspotCreateContact). It is the unit you drop into a topology.

A connector may use an Application, and most do. The Application is a shared layer that supplies authentication and user-facing settings. One Application is shared by many connectors of the same service. A connector that needs neither authentication nor shared settings doesn't need an Application at all.

Application Install #

The primary purpose of an Application is sharing: one Application encapsulates the auth method and the settings form for a service, and any number of connectors of that service reuse them.

The Application class is the type (definition + auth + form). The actual configured instance — with the user's filled-in credentials and settings — is an ApplicationInstall: a record in the platform's database that the platform creates when the Application is installed from the Admin UI.

If the connector uses an Application, the SDK loads the ApplicationInstall the message is bound to, decrypts its secrets, and calls the connector's logic with that context.

The user-facing flow:

  1. The Application declares a settings form (API key, etc.).
  2. A user opens the Admin UI, picks the Application, fills the form, saves.
  3. The platform stores the encrypted ApplicationInstall.
  4. From now on, any connector of that Application can execute against the user's account.

For OAuth-based applications, the form contains client id / secret; the install record additionally stores the OAuth tokens that the platform refreshes automatically.

Authentication flavours #

Three auth styles are supported: no auth / API key in headers, OAuth1, and OAuth2. For OAuth2, the platform handles the refresh flow; your connector code just makes the call. OAuth1 is currently available in the PHP SDK only.

The base class to extend depends on the SDK you use — the Reference overview lists the equivalent class per language for each auth flavour.

Modules #

Some Applications have several "areas" with separate sets of connectors and forms (e.g. Sales vs. Marketing in a CRM). Orchesty's Modules give you a way to group connectors and to surface module-specific settings without polluting the main settings form. See Development: Modules.

See also #

© 2025 Orchesty Solutions. All rights reserved.