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>
| Parameter | Type | Description |
|---|---|---|
name | string | The integration name, e.g. salesforce, erp, graph |
path | string | Path on the vendor API, relative to the integration's base. A leading / is added if missing. |
query | object | Query string values |
body | unknown | JSON body |
opts.request | RequestLike | Server: the incoming request |
opts.as | 'user' | 'project' | Server: 'project' calls as the app (jobs do this automatically) |
opts.headers | object | Extra headers |
Returns the vendor's parsed JSON response, or null for 202/204.
- JavaScript
- Python
// 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')
cases = tc.int.salesforce.get(
"/query", {"q": "SELECT Id, Subject FROM Case"}, request=request
)
rows = tc.int.erp.post("/query", {"sql": "select * from ar.aging", "params": []}, request=request)
# tc.int["my-system"] works for names that aren't valid attributes
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
}
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
| Code | Meaning | What to do |
|---|---|---|
ACCESS_PENDING | The project doesn't have this grant yet; a request is waiting | Show err.message. err.request is { id, status, approvers, url }. |
ACCESS_DENIED | An approver said no, or approved something narrower (for example read-only) | Work within what was granted |
CONNECT_REQUIRED | This person hasn't connected their account | tc.int.<name>.connect(); err.connectUrl has the URL |
INTEGRATION_NOT_FOUND | No integration with that name | Check list_integrations |
INTEGRATION_DISABLED, INTEGRATION_NOT_CONFIGURED | IT turned it off or hasn't finished setup | Ask IT |
VENDOR_ERROR | The vendor answered with an error | err.details is the vendor's body; err.status its status |
UNAUTHENTICATED | No signed-in user | Reload; on the server pass the request |
NO_REQUEST | Server code without a request | Pass { request: req } or use tc.middleware() |
NO_PROJECT_IDENTITY | as: 'project' outside a job | The app identity is only for cron/worker services |