Skip to main content

Integrations

Integrations let apps read and write business systems, such as Excel files in SharePoint, Salesforce cases or an on-premises ERP, without ever holding a credential. IT decides what each integration may do. Apps ask for what they need, and every call is checked and audited.

Key concepts​

ConceptWhat it is
CatalogThe integrations available in your organization, managed in Admin › Integrations. Each entry has a connection mode, approvers, max scopes and a data sensitivity.
Connection modeHow the platform authenticates to the vendor (see below).
ScopeOne permission, written <resource>:<read or write>, for example Case:read, ar.invoices:read or sites.selected:Procurement:read. A few scopes are verbs: mail.send, mail.send:owner, notify:<recipient>. * matches one segment; a trailing * matches the rest (notify:*).
IdentityWhom a call acts as: the user (each signed-in person, with their own vendor permissions) or the project (the app itself, for scheduled jobs and shared data).
GrantA project's permission to use certain scopes of an integration as a given identity, optionally with an expiry. Grants come from policies or approved access requests.
Max scopesThe ceiling IT sets per integration. Anything outside it is refused with the reason, before any request is created.
Integration GatewayThe service every call passes through. It identifies the caller, classifies the call into scopes, checks grants, uses the right credential, and audits the call.

Connection modes​

ModeUsed forHow it authenticatesWhose permissions apply
Microsoft GraphMicrosoft 365: Excel, SharePoint, OneDrive, lists, Outlook mailOn behalf of the signed-in user, or app-only per site or file (Sites.Selected) for jobsThe user's, or exactly what IT granted the app
Delegated OAuthVendors with user OAuth, such as SalesforceEach person connects their own account onceThe vendor's own permissions for that person
Org credentialSystems without OAuth, such as an on-prem SQL databaseAn admin-held service account; apps never see itThe project's grant (tables, read-only)
PlatformMicrosoft Teams messagesThe vastframe Teams bot, shared by every appThe project's grant (recipients)

Available integrations​

IntegrationModeGuide
Microsoft 365 (graph)Microsoft GraphMicrosoft 365
Microsoft Teams (teams)PlatformMicrosoft Teams
Salesforce (salesforce)Delegated OAuthSalesforce
On-prem ERP / SQL (erp)Org credentialOn-premises SQL database
Availability

On a new Azure installation the catalog starts with Microsoft 365 and Microsoft Teams. Salesforce and the ERP connection are part of the local development stack, backed by local stand-ins. Adding new catalog entries from the console isn't available yet; existing entries are configured in Admin › Integrations.

How a call flows​

Apps call integrations through the SDK, which talks to the gateway at /_tc/int/<integration>/… on the app's own origin (browser) or at $TC_GATEWAY_URL (server code and jobs).

// As the signed-in user, in the browser or on the server
const { records } = await tc.int.salesforce.get('/query', {
q: 'SELECT Id, Subject, Account.Name FROM Case WHERE IsEscalated = true',
});

For each call, the gateway:

  1. Identifies the caller: the signed-in user from X-TC-User, or the project from the job's project token.
  2. Classifies the call into scopes: Graph paths, SOQL objects or SQL tables. Calls it can't classify are refused.
  3. Checks grants with the Hub. Allowed answers are cached for up to 3 seconds; approvals, denials and revocations flush the cache. Ungranted calls answer ACCESS_PENDING and create a request if there isn't one.
  4. Uses the right credential for the mode.
  5. Audits the call: project, user, integration, operation, status, size and duration.

Approvals take effect on the next call. No redeploy is needed.

Declaring what an app needs​

List integrations in tc.json so requests are filed at deploy time with a purpose approvers can read:

{
"integrations": { "salesforce": ["Case:read", "Account:read", "Case:write"] },
"purpose": "Support leads see open Salesforce escalations grouped by account owner"
}

The deploy also scans your code for tc.int.<name>, tc.m365.* and tc.teams.notify calls and records the file and line of each. See Building apps.

The project's Integrations page​

Open a project and select Integrations to see:

  • Data sources: Microsoft 365 files the app reads, and how many viewers can open each
  • Grants in effect: what the app can reach, as whom, with expiry; owners can revoke a grant
  • Requests: pending and decided requests for this app
  • Your connections: your own connected vendor accounts
  • Detected in code: integrations found by the deploy scan
  • Recent calls: the gateway's audit of this app's calls
  • Request access: ask for a scope by hand, with a one-line reason
Was this page helpful?