Skip to main content

Integrations

tc.int.<name> calls the vendor's own REST API through the Integration Gateway. The gateway adds the credentials, checks the project's grants and audits every call. You never store vendor credentials or ask people for API keys.

IT connects integrations once. To see which ones exist, use the MCP tool list_integrations or the console. Connection modes and approvals are covered in Integrations.

Calling an integration​

tc.int[name].get<T>(path: string, query?: Record<string, string | number | boolean>, opts?: CallOpts): Promise<T>
tc.int[name].post<T>(path: string, body?: unknown, opts?: CallOpts): Promise<T>
tc.int[name].patch<T>(path: string, body?: unknown, opts?: CallOpts): Promise<T>
tc.int[name].put<T>(path: string, body?: unknown, opts?: CallOpts): Promise<T>
tc.int[name].delete<T>(path: string, opts?: CallOpts): Promise<T>
tc.int[name].request<T>(method: string, path: string, o?: { query?; body?; opts?: CallOpts }): Promise<T>
ParameterTypeDescription
namestringThe integration name, e.g. salesforce, erp, graph
pathstringPath on the vendor API, relative to the integration's base. A leading / is added if missing.
queryobjectQuery string values
bodyunknownJSON body
opts.requestRequestLikeServer: the incoming request
opts.as'user' | 'project'Server: 'project' calls as the app (jobs do this automatically)
opts.headersobjectExtra headers

Returns the vendor's parsed JSON response, or null for 202/204.

// Salesforce: per-user OAuth, so each person sees only what Salesforce lets them see
const { records } = await tc.int.salesforce.get('/query', {
q: 'SELECT Id, Subject, Account.Name FROM Case WHERE IsEscalated = true',
})
await tc.int.salesforce.patch(`/sobjects/Case/${id}`, { Status: 'Working' })

// An org-credential system: read-only SQL, granted by table
const { rows } = await tc.int.erp.post('/query', {
sql: 'select * from ar.aging where total_open > $1',
params: [1000],
})

// Microsoft Graph
const me = await tc.int.graph.get('/me')

Permissions never dead-end​

Declare what you use in tc.json ("integrations": { "salesforce": ["Case:read"] } plus a one-line "purpose"), or just call it: the deploy scans your code and asks for whatever is missing. The app goes live either way.

Until someone approves, ungranted calls throw ACCESS_PENDING. Once approved they start working with no redeploy.

try {
const { records } = await tc.int.salesforce.get('/query', { q })
} catch (err) {
if (err.code === 'ACCESS_PENDING') {
showBanner(err.message) // names the request number and the approver
console.log(err.request.url) // the request in the console
} else if (err.code === 'CONNECT_REQUIRED') {
tc.int.salesforce.connect() // one click, once per person
} else throw err
}
warning

Don't retry ACCESS_PENDING in a loop. Show the message. Jobs should log it and exit 0; they're re-run as soon as the grant is approved.

Browser-only helpers​

For integrations that use per-user OAuth (delegated), each person connects their own account once.

connect(returnTo)​

Sends the browser through the vendor's consent screen and back.

tc.int[name].connect(returnTo?: string): void

status()​

tc.int[name].status(): Promise<{ connected: boolean; user: { name?: string; email?: string } | null; connectUrl: string | null }>

disconnect()​

Drops this person's connection.

tc.int[name].disconnect(): Promise<unknown>

Errors​

CodeMeaningWhat to do
ACCESS_PENDINGThe project doesn't have this grant yet; a request is waitingShow err.message. err.request is { id, status, approvers, url }.
ACCESS_DENIEDAn approver said no, or approved something narrower (for example read-only)Work within what was granted
CONNECT_REQUIREDThis person hasn't connected their accounttc.int.<name>.connect(); err.connectUrl has the URL
INTEGRATION_NOT_FOUNDNo integration with that nameCheck list_integrations
INTEGRATION_DISABLED, INTEGRATION_NOT_CONFIGUREDIT turned it off or hasn't finished setupAsk IT
VENDOR_ERRORThe vendor answered with an errorerr.details is the vendor's body; err.status its status
UNAUTHENTICATEDNo signed-in userReload; on the server pass the request
NO_REQUESTServer code without a requestPass { request: req } or use tc.middleware()
NO_PROJECT_IDENTITYas: 'project' outside a jobThe app identity is only for cron/worker services
Was this page helpful?