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
| Concept | What it is |
|---|---|
| Catalog | The integrations available in your organization, managed in Admin › Integrations. Each entry has a connection mode, approvers, max scopes and a data sensitivity. |
| Connection mode | How the platform authenticates to the vendor (see below). |
| Scope | One 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:*). |
| Identity | Whom 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). |
| Grant | A 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 scopes | The ceiling IT sets per integration. Anything outside it is refused with the reason, before any request is created. |
| Integration Gateway | The 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
| Mode | Used for | How it authenticates | Whose permissions apply |
|---|---|---|---|
| Microsoft Graph | Microsoft 365: Excel, SharePoint, OneDrive, lists, Outlook mail | On behalf of the signed-in user, or app-only per site or file (Sites.Selected) for jobs | The user's, or exactly what IT granted the app |
| Delegated OAuth | Vendors with user OAuth, such as Salesforce | Each person connects their own account once | The vendor's own permissions for that person |
| Org credential | Systems without OAuth, such as an on-prem SQL database | An admin-held service account; apps never see it | The project's grant (tables, read-only) |
| Platform | Microsoft Teams messages | The vastframe Teams bot, shared by every app | The project's grant (recipients) |
Available integrations
| Integration | Mode | Guide |
|---|---|---|
Microsoft 365 (graph) | Microsoft Graph | Microsoft 365 |
Microsoft Teams (teams) | Platform | Microsoft Teams |
Salesforce (salesforce) | Delegated OAuth | Salesforce |
On-prem ERP / SQL (erp) | Org credential | On-premises SQL database |
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:
- Identifies the caller: the signed-in user from
X-TC-User, or the project from the job's project token. - Classifies the call into scopes: Graph paths, SOQL objects or SQL tables. Calls it can't classify are refused.
- 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_PENDINGand create a request if there isn't one. - Uses the right credential for the mode.
- 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