Connect AI tools
Control what a tool may do
Limit a connected AI tool with scopes, databases and allowed addresses, approve the risky steps it asks for, and review everything it did in the activity list.
Several layers decide what a connected AI tool can do. Each layer can only narrow access, never widen it.
- The organization. Your plan has to include AI tool access, and advanced scopes need advanced access for your organization. See Connect AI tools.
- The application's permissions. The application needs the permission External AI tools, and whatever organization permissions a step requires, just like a person would.
- Access rules. The tool sees only the views the application has been given, with their hidden columns and row filters. See Access.
- Scopes. The kinds of work the application may do at all.
- Databases and addresses. Where the application may connect to, and from.
- Approvals. A few steps always wait for a person.
If a call fails a check, the tool receives a short reason, such as insufficient_scope or insufficient_permission, and nothing changes.
Scopes#
Open Settings, Developer Tools, Applications, click Manage, and find What this application may do in the AI tool access section. A new application can only read.
| Scope | What it allows |
|---|---|
| Read records and history | Rows, comments, change history, workflow runs and files in views shared with the application. |
| Create and change records | Create, update and delete rows, add comments, attach files, and restore from the trash. |
| Change the structure | Tables, columns, views, layouts, pages, dashboards, documents and business rules. Deleting data needs an explicit confirmation. |
| Create and change workflows | Write and update workflows. |
| Run workflows and buttons | Start workflows and entry buttons, and cancel runs. |
| Decide approval requests | Approve or reject requests that are assigned to this application, and only those. |
| Send data out and publish | Create workflows that send email or call other services, and public pages and forms. |
| Use the assistant | Let the tool hand a request to the SAPUGO assistant. The assistant stays inside the scopes above. |
Writing and running always include reading, so Read records and history is added for you when you grant anything else.
Every scope except the first two needs advanced AI tool access for your organization. Without it, those scopes are greyed out with the note Needs advanced AI tool access for this organization.
You also need to be allowed to do the work yourself. To grant Change the structure you must be able to create tables and views, and to grant a workflow scope you must be allowed to manage workflows. Organization owners can grant all of them.
Limit the databases#
Under Databases, tick the databases the application may use. Leave all unticked to allow every database the application can reach. A tool that tries another database is refused.
Limit where it connects from#
Under Allowed addresses, enter one address or range per line, such as 203.0.113.5 or 203.0.113.0/24. The key then works only from those addresses, even if it leaks. Leave the list empty to allow any address.
Click Save access limits to apply the scopes, databases and addresses.
Approve what needs a person#
Some steps don't run straight away, even when the scope allows them. The tool is told that the step is waiting and gets a request id to check later.
| Step | Why it waits |
|---|---|
| A workflow that would send data out of your organization, for example by email or to another service | Unless the application has Send data out and publish. |
| A change that could lose data, when no backup could be taken first | SAPUGO won't risk the data without a person's decision. |
Waiting steps appear under Waiting for your approval on the Applications page, with Show what would run, Approve and Reject. An approved step runs as the application and never with more access than the application already has.
Other risky steps need the tool to confirm them in the same call. Deleting a table, a column or a workflow, converting a column to another type, and creating or updating more than 50 records in one call are refused until the tool says it is sure. For a large change, the tool can first do a dry run to see what would happen.
Where a change could lose data, SAPUGO takes a backup first. The tool is told to repeat its call once the backup is ready.
See what it did#
Open Manage on the application and switch to the Agent activity tab. Each call shows the tool that was used, the table, view and record it touched, and whether it was Done, Held back or Failed. You can filter the list by outcome. Calls made on the tool's behalf by the assistant are marked via assistant.
Only names and ids are kept, never the values or arguments of a call. Activity is kept for 90 days.
Switch a tool off#
- Revoke a key under API keys in the application. It stops working at once.
- Disable the application to stop all of its keys without deleting anything. Enable brings it back.
- Delete the application to remove it and its keys for good.
Keys can also expire on their own. Set Expires (days) when you issue one, and issue a fresh key on a schedule.
Good habits#
- Create one application per tool or per team, so you can tell them apart in the activity list and switch one off on its own.
- Grant the smallest set of scopes that does the job. Start with read only.
- Give the application its own group and share views with that group, instead of giving it broad access.
- Set Expires (days) and Allowed addresses for tools that run on a server.
- Be careful with records that outsiders can fill in, such as form submissions. A tool reads their text as data, but a person using the tool should still check what it proposes to do.
Discussions about this page
Stuck, or found something missing? Ask the community.