Permissions and Safety
Scopes
Every connection carries permission scopes: the ones approved at the OAuth consent screen, or the ones on the API key. The tool list is filtered to match, so a read-only connection has no write tools at all. If the assistant reports it lacks a tool, that is the filter working.
The scope areas are the same as everywhere on the API page: Sources, Datasets, Ontology, Digital Twins, Simulations, Connectors, Catalog, Jobs, Exports, Agent, and Reports (see API Access).
Standard MCP clients request the default bundle: read access to your content plus the Agent scopes.
Read scopes cover exploring, querying, and previewing, including viewing simulation results. Running a simulation (an execute action), Connectors, and Exports are not included.
Agent scopes cover the assistant's own working surface: loading skills, building charts, searching documentation, usage queries, building and running Applications.
Nothing in the default bundle can change your content: no editing datasets or ontology, no creating or training twins, no imports.
To grant write access, connect with an API key carrying the write scopes you choose. The consent screen shows a client's requested scopes as a fixed list, so a broader OAuth grant is only possible for clients built to request one.
A connection pinned to one workspace at consent refuses every other workspace, regardless of scopes.
Confirmation gate
Tools that change ground truth, cannot be undone, or take a long time do nothing on the first call: the server replies that nothing has happened and the assistant must ask you before calling again with explicit confirmation. This gate covers:
Shared truth: editing the ontology, modifying a dataset definition, updating or retiring a Digital Twin
Irreversible actions: deleting a dataset or twin, publishing an Application (publishing makes it runnable outside the chat: REST endpoints, schedules, webhooks)
Long-running work: training, causal discovery, external imports. The confirmation includes a duration hint.
Reading, querying, previewing, and simulating run without ceremony.
Background jobs
Imports, discovery, and training return a run id immediately and complete in the background. The assistant polls (check_background_runs) and reports when the job lands. These are the same background jobs visible in the workspace UI.
Rate limits
OAuth connection
120 requests per minute
API key
60 per minute by default, configurable per key
Responses carry X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset; a limited request gets 429 with Retry-After. Conversational use does not hit these; they stop runaway loops.
Revoking and auditing
Revoke: every authorized client is listed in Connected Apps on the API page. Revoking deletes the grant and its refresh tokens immediately; an already issued access token can outlive revocation by up to 15 minutes.
Audit: tool failures and AI cost events land in the organisation audit log, queryable conversationally (see What You Can Do).
Key hygiene (legacy method): scope narrowly, set an expiry, use the IP allowlist, rotate. See API Access.
Last updated