Docs Access
Scopes
The six permissions a connection or key can carry, and what each one opens.
A scope is a permission. A connection or key carries one or more, chosen when it is created. The server only lists the tools those scopes allow, so an app never sees a tool it cannot call.
| Scope | Name in Soontra | What it allows |
|---|---|---|
read | See your workspace | Browse projects, posts, comments, links, notifications and Drive file names, paths and descriptions. Always included. |
content | Read file content | Search, and read transcripts, captions, summaries and document text, for files whose AI indexing is turned on. |
analytics | View analytics | See audience and performance figures for connected channels, from Soontra’s stored results. It never asks a network for fresh numbers. |
directory | See your team | See teammates’ names and roles. |
download | Download files | See small image previews, play video and audio inside the AI app, and create download links that last 15 to 60 minutes. |
write | Create and edit drafts | Create and update projects, subtasks, comments, documents, folders and post drafts, and upload files. It cannot publish or delete. |
Access levels
When an AI app signs in, Soontra offers three access levels. Each is a set of scopes.
| Access level | Scopes |
|---|---|
| Full access | read, content, analytics, directory, write |
| Content access | read, content, analytics, directory |
| Read-only | read |
download is in none of them. It is a separate box under Advanced options, and a separate switch on an API key. An API key starts with read only; add the rest one by one.
Things to know
- Download links are bearer links. Anyone holding one can download that file until it expires, including another tool you pass it to. Grant
downloadonly where that is acceptable. - Content follows indexing.
contentreads only files whose AI indexing is on. A file that was never indexed has no transcript or summary to return. - Drive roots. File and folder tools work on the Team drive unless a call names Personal or Shared with me. New files and folders go to Team by default, never to Shared with me.
- Some writes need more than the scope. Creating or renaming a workflow stage needs an owner’s or admin’s credential. Editing a shared document needs the document to be shared with edit rights.
- Deletion cannot be granted. Tools that delete exist in Soontra but are never listed to a connected app.
Checking what a connection has
Call soontra_workspace_getContext. Its answer includes granted_scopes and available_tools for the credential that asked.