Instances and credentials

An instance is one connection to a source system: a base URL, credentials, headers and parameters. Several instances load the same datasets from several companies or tenants; every stored row carries the instance name in _instance, and record ids are prefixed with it unless the source system is single-instance.

The Instances section

Inside an expanded source system, Instances lists Instance, Base URL, Auth Type (with a sign-in expiry chip for Microsoft sign-in), Status (the enabled switch; replaced by Renaming… while a rename runs) and actions: Refresh now, Copy API trigger URL, Duplicate (copies the base URL, credentials, headers and query parameters, so a second company is a copy plus an edited base URL) and Edit. Add Instance is disabled at the plan's cap of instances per source system, and hidden on a single-instance system that has its instance.

A new instance starts disabled. A disabled instance, source system or dataset is skipped by jobs, schedules and trigger URLs at the moment a load is queued; a person pressing a dataset's Refresh now still passes the switch.

Create or edit an instance

New Instance asks for the basics; after Create the dialog stays open and switches to the three tabs Edit instance, Credentials and Configurations.

Edit instance

• Instance Name — unique within the source system (case-sensitive), at most 50 characters. On edit it is locked behind a padlock; see Rename an instance.

• Base URL (cloud) — may contain {{variables}}.

• Authentication Type (cloud):

  Type	What it does
  None	No authentication
  Basic	HTTP Basic Auth (user id and password)
  Bearer	A static bearer token
  Header	Auth values sent as HTTP headers. Put the key in Headers on the Configurations tab
  Query Parameter	Auth values added as query parameters. Put the key in Parameters
  Session Bearer	POST to a token URL to acquire a bearer token before each load. Use this for OAuth 2.0 client credentials
  Session Bearer (Basic Auth)	The same, with basic auth on the token request
  Microsoft sign-in	Sign in once as a Microsoft 365 account; loads run with its permissions

Credentials

For most types the Credentials tab holds a key/value table and a Setup Credentials button that opens a form for the saved authentication type (save the instance after changing the type, then set up the credentials). Every field accepts {{variables}}, and that is the way to keep a secret out of the instance: credential values are stored as typed and shown in the table, so put a password in an encrypted or Key Vault variable and reference it.

Session Bearer asks for the Token URL, a body (Form data for OAuth 2.0 client-credentials flows such as Microsoft Entra and Business Central, which need grant_type, client_id, client_secret and scope; Raw / JSON for endpoints that take JSON), optional headers, and where the token is in the response: Token Nested Path and Token Field Name. Preview token response POSTs to the token URL and lets you click the field that holds the token.

Token reuse. A session-bearer login mints a new token for every dataset load, so a job over 20 datasets makes 20 token requests, often the first thing a rate-limited API throttles. Reuse the session token across loads lets loads share a token while it is still valid, with a safety margin so it cannot expire part-way through a load. A load that gets 401 with a reused token mints a fresh one once and retries.

Microsoft sign-in replaces the table with a sign-in panel:

• Scope — the Microsoft scope for the API this instance calls, for example https://graph.microsoft.com/.default.
• Advanced — the Tenant (an id, a domain, common, or a variable), and Use this deployment's Microsoft app registration. Leave it on unless the deployment's registration lacks the delegated permissions you need; off, enter a Client ID and optionally a Client secret, which may reference an encrypted or Key Vault variable.
• Connect… — save the instance first, then connect. A popup opens for the sign-in and the refresh token is stored encrypted. The loads then run as the account that signed in, with that account's own permissions, so sign in as a service account that is a member of the sites or data it should read. The panel shows Signed in as, when the token was last acquired, and an Expires in N day(s) chip. The refresh token is renewed on every load and lapses after 90 days without one; the failure-notification recipients are emailed a week before. A password reset or a disabled account ends the sign-in; press Connect… again.

The sign-in needs the API URL followed by /api/auth/oauth/callback under the Web platform of the Cloud Connector app registration (see After deployment: activation and redirect URIs), and delegated permissions with admin consent for whatever the scope asks for.

Configurations

• Headers — sent on every request of the instance, as Key / value rows or a raw JSON object. Values may contain {{variables}}. An endpoint header with the same name overrides the instance's.
• Parameters — sent as query parameters on every endpoint of the instance, in addition to each endpoint's own; an endpoint parameter with the same key wins.
• Body — the default request body for POST endpoints, Raw / JSON or Form data. An endpoint body of the same kind is merged over it, key by key; a body of another kind replaces it.
• Pagination (NextLink) — the paging rule every endpoint without one of its own inherits. The options are those of the endpoint, see Pagination.

Rename an instance

Unlock Instance Name, type the new name and save. A confirmation explains what follows: every loaded row of the instance is re-keyed and its exported SQL and Fabric tables are rebuilt, so exported _id values change and any report or join built on them breaks. While the rename job runs, loads, Gateway syncs and webhooks for the source system are paused and its settings are locked; rows may briefly appear twice in the warehouse. Large datasets take a while; the job runs in the background and reports in the Dataset log. A rename is refused while a load of the instance is queued or running.

On-prem instances

An instance of an on-premises source system has only a name. Its Edit Instance dialog adds the panel On-prem push (Cloud Connector Gateway): Generate key issues a scoped agent key (shown once), and Gateway connection details gives the Base URL, Source system instance ID and the key to paste into the Gateway's Setup UI. The key table shows every key with its label, last use and a Revoke action. See On-Prem Gateway.

Delete an instance

Delete in the dialog removes the instance record only. Its loaded rows and its credential rows stay behind; drop the datasets' collections, or delete the source system, when the data should go too.