Skip to main content
Connectors let Ingestly interact with external services on your behalf. Once a connector is set up, workflow nodes such as the HTTP action and callback output can make authenticated requests through it without exposing credentials in the workflow configuration. A connector is an identity (a name, a type, and an authentication method) with a separate credential profile for each workflow environment. Each connector has a Development profile and a Production profile, each with its own status and encrypted credentials. This keeps building-and-testing credentials separate from the credentials used by live Production workflows. See workflow environments for details.

​
Connector catalog

Open Settings and select Connectors, then click New Connector to browse the catalog. Ingestly offers six connector types:

​
Creating a connector

  1. Click New Connector and pick a type from the catalog.
  2. Read the Setup instructions shown with the form. Each type lists the prerequisites you need on the external service (for example registering an app, choosing scopes, or copying an identifier into the form).
  3. Give the connector a name.
  4. Configure the Development credentials. This profile is required and is used while you build and test the connector.
  5. Optionally configure the Production credentials now, or add them later. Production credentials are used when a workflow runs in Production.
  6. Save the connector.
Production credentials are optional at creation. You can create a connector with only its Development profile connected and add Production later from the connector’s edit dialog. Connect the Production profile before you copy a workflow that uses it into Production.

​
QuickBooks Online (OAuth)

For QuickBooks Online, click Connect to start the OAuth flow for that environment. You sign in on Intuit’s consent screen and grant the requested permissions, then you are redirected back to Ingestly when authorization completes.

​
Business Central (client credentials)

Business Central uses an app-only connection: Ingestly requests tokens directly from Microsoft with your app registration’s client ID and secret. There is no sign-in or consent screen, and the connection does not expire from inactivity. Before creating the connector:
  1. Register an app in Microsoft Entra ID and grant it the Application permission Dynamics 365 Business Central > API.ReadWrite.All with admin consent.
  2. Create a client secret and note its expiry date.
  3. In Business Central, open Microsoft Entra Applications, add the app’s client ID, set its state to Enabled, and assign a user permission set that covers the entities you write.
  4. To confirm purchase orders from vendor confirmations, install the Ingestly Connector extension, turn on Enable purchase order amendments in its setup page, and assign the Ingestly Purchase Amendment permission set to the same application. The Business Central node’s Confirm Purchase Order operation checks this and reports Purchase order confirmations are supported when both are in place.
Each environment profile takes:
  • Tenant ID, Client ID, Client Secret from the app registration.
  • Secret expires on (optional): the secret’s expiry date. Ingestly shows a warning beside the profile status 30 days before it lapses and marks it expired on and after that date. Rotate the secret from the profile’s Rotate credentials panel.
  • Environment: the Business Central environment name (for example production). Use 1 to 50 characters made up of letters, digits, dots, underscores, or hyphens.
  • Company ID: the company GUID. It is required and must be a valid GUID.
Save the connector (or click Connect on the profile in the edit dialog). Ingestly requests a token immediately, so a wrong secret or a missing permission fails right away with Microsoft’s reason. Use Save settings to change the Environment, Company ID or expiry date later.

​
API Key connectors

The API Key connector is not an OAuth integration. Instead you supply one or more header credentials and a base URL:
  • Header rows: one or more Header name and Header value pairs sent with every outbound request (for example Authorization: Bearer ... or X-Api-Key: ...).
  • Base URL: the host outbound requests are restricted to.
Click Connect to save and validate the profile.

​
OAuth 2.0 (authorization code)

Use the OAuth 2.0 connector for any API that authenticates through a provider’s consent screen. Before creating the connector, register an app with the provider and set its redirect URI to the value shown in the connector’s setup instructions: {your-ingestly-server-url}/connectors/oauth/callback. The setup instructions in the app show this with the placeholder already filled in for your server. Each environment profile takes:
  • Authorization URL: the provider’s authorization endpoint, where the user signs in and grants access.
  • Token URL: the provider’s token endpoint, used to exchange the authorization code, and later the refresh token, for an access token.
  • Scopes: space-separated scopes to request.
  • Audience (optional): the audience some providers require to scope the token to a specific API.
  • Token endpoint auth: how client credentials are sent to the token endpoint: Request body (client_secret_post) or HTTP Basic header (client_secret_basic).
  • Use PKCE: on by default, using the S256 challenge method. Leave it on unless the provider does not support PKCE.
  • Extra parameters: key/value pairs sent to both the authorization and token requests, for example access_type=offline to make a provider issue a refresh token. Reserved OAuth parameter names such as client_id, scope, state, and redirect_uri are rejected here because Ingestly sets them itself.
  • Base URL: the host outbound requests through this connector are restricted to.
Click Connect to start the flow for that environment. A consent popup opens on the provider’s authorization page, and the environment is marked Connected once you finish granting access.
Changing the Authorization URL, Scopes, or Audience disconnects the environment: reconnect after changing any of them. Changing the Token URL or Base URL also disconnects the environment and clears its stored client credentials, because those hosts are the ones that receive the secret and the tokens; enter the Client ID and Client Secret again to reconnect. Disconnecting clears the stored credentials but keeps this configuration, so reconnecting does not require retyping it.

​
Refresh and expiry

Ingestly refreshes the access token five minutes before it expires, using the refresh token the provider issued during the original authorization.
If the provider never issued a refresh token, or the stored refresh token is no longer valid, the profile shows Expired once the access token lapses. Reconnect the environment to restore it. Some providers only issue a refresh token when the authorization request carries an extra parameter (for example access_type=offline); add it under Extra parameters if reconnecting keeps expiring.

​
Security

  • The Authorization URL and Token URL must use https. http is accepted only for localhost, for local development.
  • Requests through the connector are restricted to the connector’s Base URL host; private network and internal addresses are refused.
  • Client secrets are encrypted at rest and are never shown again after saving.
  • If the token endpoint cannot be reached or returns an invalid response, Test shows a fixed error message instead of the raw provider response. A provider’s own error_description for rejected credentials is still shown.

​
OAuth 2.0 (client credentials)

Use the OAuth 2.0 (Client Credentials) connector for an API that authenticates app-only, with no user sign-in. Each environment profile takes the same Token URL, Scopes, Audience (optional), Token endpoint auth, Extra parameters, and Base URL fields as OAuth 2.0 (authorization code). There is no Authorization URL and no PKCE option, since client credentials never involve a browser redirect. Click Connect to mint a token immediately. The environment is marked Connected on success, or Error if the token endpoint rejects the client credentials. There is no refresh token in this flow. Ingestly requests a fresh token directly from the token endpoint whenever the current one is close to expiring, the same as the Business Central connector’s client credentials connection. The same https-only rule, Base URL host restriction, encrypted secrets, and fixed error message on an unreachable or invalid token endpoint apply here as well. Disconnecting clears the stored credentials but keeps the rest of the configuration.

​
Basic Auth

Use the Basic Auth connector for an API that authenticates with a plain username and password:
  • Username
  • Password (may be left blank)
  • Base URL: the host outbound requests are restricted to.
Ingestly composes the Authorization header from the username and password; you never need to build it yourself. Click Connect to save the credentials and mark the environment Connected; it does not call the Base URL. Use Test afterwards to verify the credentials against it. Changing the Base URL of a connected environment clears the stored credentials and disconnects it, since that host is the one that receives them; enter the password again to reconnect. To rotate a stored password to an empty one, tick Use an empty password before clicking Rotate. Disconnecting clears the stored credentials but keeps the Base URL configuration.

​
Managing connectors

The connectors list shows a Name column, a Type column, and two status columns: Development and Production. Each status column shows the profile’s status for that environment, or Not set when that environment has no profile configured yet. Each row has two actions:
  • Edit: open the connector’s edit dialog. The dialog shows both environment profiles (Development and Production) side by side so you can configure, test, or rotate either one.
  • Delete: permanently remove the connector.

​
Per-environment profile actions

Test, disconnect, and credential rotation are configured separately for each environment inside the edit dialog. Each profile offers:
  • Connect: shown when the profile is not connected. Enter the credentials and connect that environment.
  • Test: verify a connected profile is still authorized and healthy.
  • Disconnect: revoke that environment’s access while keeping the connector entry.
  • Rotate credentials: replace a connected profile’s credentials without re-authorizing from scratch.
There is no standalone Rotate Credentials dialog. Rotation lives in each environment profile inside the connector’s edit dialog, alongside Test and Disconnect.

​
What rotation asks you to re-enter

Rotation only ever asks for the secret parts. Everything Ingestly can safely echo back is prefilled, so swapping a secret does not mean retyping the whole profile.
  • Client credentials profiles (Business Central app-only): the panel opens with the Client ID and Tenant ID already filled in. Only the new Client Secret is required. Set Secret expires on at the same time so the expiry warning tracks the new secret.
  • API Key profiles: the Base URL and the Header name of each stored header are prefilled, with the header values blank. Re-enter the values. A rotate replaces the whole header set, so remove a row here to drop that header.
After a successful rotation the secret field is cleared and the panel stays open, so you can confirm the profile reconnected without reopening it.

​
Connector status

Each environment profile reports one of these statuses:
You cannot delete a connector that is referenced by a workflow. Remove the connector from any workflow that uses it first, then delete it.

​
Permissions

Managing connectors requires the Account.Connector permission. Among the built-in roles only Admins have it, but you can grant it to a custom role. See roles and permissions for details.