Skip to main content

Tools: access, settings and integrations

Access​

get_access​

Who can open the project's app: the mode, the people and groups allowed, app roles, and what the live team / department rules resolve to now.

InputTypeRequired
projectstringYes

set_access​

Changes who can open the app. Owner, project developers or an Org Admin; audited. Omitted fields keep their current value.

InputTypeRequiredDescription
projectstringYes
mode"only_me" | "team" | "department" | "groups" | "everyone"NoSee below
membersstring[]NoPeople and groups for groups mode. Replaces the list.
rolesRecord<string, string[]>NoApp roles, e.g. { "approver": ["Finance - FP&A"] }. They reach the app in the X-TC-User token's roles claim.

A member is a user email (megan.bowen@contoso.com), a group name ("Finance - FP&A") or a directory object id.

ModeWho can open the app
only_meThe owner only (default for new projects)
teamThe owner's manager's direct reports, resolved live from the directory
departmentThe owner's department, live
groupsThe owner plus members
everyoneAnyone in your organization (your company's directory)

Returns the new access settings; the summary reads "expenses can now be opened by the owner + Operations".

Settings​

list_env​

The project's environment variables. Secret values are never returned (they're masked); plain values are. pendingRedeploy means there are changes the running app doesn't have yet.

InputTypeRequired
projectstringYes

set_env​

Adds, changes or removes environment variables. Owner, project developers or an Org Admin; audited by name only. Values are stored encrypted, and secrets are write-only afterwards. Names starting with TC_, and DATABASE_URL and PORT, are reserved.

InputTypeRequiredDescription
projectstringYes
vars{ name, value, secret? }[]NoVariables to add or change
unsetstring[]NoNames to remove
redeploybooleanNoRedeploy the current production build now (no rebuild) so the app sees the change

Pass at least one of vars, unset or redeploy: true, otherwise you get NOTHING_TO_DO.

Returns { env, redeployed }.

delete_project​

Deletes a project for good: the app, preview URLs, Data API, database, files and grants. Pending access requests are cancelled, an audit record is kept, and the name becomes free. Owner or org admin only.

InputTypeRequiredDescription
projectstringYes
confirmstringYesThe exact project name, typed by the person to confirm
danger

Irreversible. Agents should ask the person first, and suggest archiving if they might want the app back. A confirm that doesn't match returns CONFIRM_MISMATCH.

Integrations and access requests​

See Integrations for how grants and approvals work.

list_integrations​

Integrations IT has connected and enabled.

Input: none.

Returns an array of { name, displayName, mode, how, maxScopes, approvers, description }. name is what app code uses in tc.int.<name>.

describe_integration​

How to call one integration from app code (SDK and raw paths), its scopes and who approves them.

InputTypeRequired
namestringYes

Returns the integration plus a usage hint, for example for salesforce: tc.int.salesforce.get('/query', { q: … }).

Errors: INTEGRATION_NOT_FOUND.

request_grant​

Asks for integration access for a project (owner or org admin), or, with share_file, asks to show a Microsoft 365 file's data to everyone who can open the app. Policies may approve it at once; otherwise it's routed to the integration's approvers (and the manager, for sharing) with a Teams card.

InputTypeRequiredDescription
projectstringYes
integrationstringWith scopese.g. salesforce, graph, erp, teams
scopesstring[]With integratione.g. ["Case:read", "Account:read"]
identity"user" | "project"Nouser (default): as each signed-in user. project: as the app itself (jobs, snapshots).
purposestring (3–500)YesOne line for approvers, in the person's words
share_filestringNoA SharePoint URL whose data should be visible to everyone with app access. The request states how many viewers can't open the file today.

Returns { status, autoApproved, request, grant }. status is covered (already granted), granted (approved by a policy), pending or denied. With share_file, it returns { request, autoApproved }.

Errors: BAD_REQUEST without integration + scopes or share_file; READ_ONLY / PROJECT_NOT_FOUND if you can't manage the project.

list_requests​

Access requests for a project, or all of yours: status, scopes, approvers, the decision (approved narrower, or denied with a reason) and questions from approvers.

InputTypeRequiredDescription
projectstringNoDefault: every request you made
status"pending" | "approved" | "denied" | "withdrawn" | "all"NoDefault: all

Returns an array of { id, status, project, integration, scopes, identity, summary, approvers, decision, messages, url }, where url opens the request in the console.

Was this page helpful?