# 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 `download` only where that is acceptable.
- **Content follows indexing.** `content` reads 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.