<!-- Source: https://docs.squirro.com/en/latest/technical/api/squirro_client/sc-api-permissions.html -->
# Permissions Reference

Squirro uses two independent permission layers that both apply on every API request.

- **Server-level permissions** — determined by the user’s tenant role (`admin`, `user`,
  `reader`). They control what the account can do across the tenant, such as creating
  projects or accessing the Server space.
- **Project-level permissions** — determined by the project role the account holds in a
  given project (`admin`, `member`, `reader`). They control what the account can do
  within that project, such as reading items or managing sources.

When using a service account token with `project_permissions` scoped on `new_grant()`,
a third layer applies: the token permissions act as an additional restriction on top of the
project-level permissions. The effective permissions are the intersection of all three layers.
See [Create a Service Account](service-account.md#service-account) for a practical guide.

Permission strings use dot-notation with glob-style wildcards. For example, `items.*`
matches any permission starting with `items.`, while `items.read.*` matches only
read operations on items.

## Project Role Permissions

**Admin** and **Owner** roles are granted `*`, giving them full access to all project
resources with no restrictions.

The table below lists the permissions granted to the **Member** and **Reader** project roles.
These are also the strings you can use in the `project_permissions` parameter of
`new_grant()` to scope a service token to a subset of operations.

| Permission | Description | Member | Reader |
| --- | --- | --- | --- |
| `collections.*` | Full access to collections (create, read, modify, delete) | ✓ | ✓ |
| `community_subscriptions.*` | Subscribe and unsubscribe from communities | ✓ | ✓ |
| `community_types.delete.*` | Delete community types | ✓ |  |
| `community_types.read.*` | Read community types | ✓ | ✓ |
| `community_types.write.*` | Create and modify community types | ✓ |  |
| `communities.delete.*` | Delete communities | ✓ |  |
| `communities.read.*` | Read communities | ✓ | ✓ |
| `communities.write.*` | Create and modify communities | ✓ |  |
| `dashboards.*` | Full access to dashboards | ✓ |  |
| `dashboards.read.*` | Read dashboards |  | ✓ |
| `dss.feedbacks.read.*` | Read DSS feedback | ✓ | ✓ |
| `dss.feedbacks.write.*` | Create and modify DSS feedback | ✓ | ✓ |
| `enrichments.delete.*` | Delete enrichments | ✓ |  |
| `enrichments.read.*` | Read enrichments | ✓ |  |
| `enrichments.write.*` | Create and modify enrichments | ✓ |  |
| `facets.read.*` | Read facets | ✓ | ✓ |
| `guide_files.read.*` | Read guide files | ✓ | ✓ |
| `ingester.read.*` | Read ingester status and configuration | ✓ |  |
| `ingester.write.*` | Trigger ingester operations | ✓ |  |
| `items.*` | Full access to items | ✓ |  |
| `items.read.*` | Read items |  | ✓ |
| `items.write.update.read_state` | Mark items as read or unread |  | ✓ |
| `items.write.update.starred_state` | Bookmark items |  | ✓ |
| `ml.*` | Full access to machine learning resources | ✓ |  |
| `ml.*.read.*` | Read machine learning resources |  | ✓ |
| `ml.groundtruths.labels.*` | Full access to ground truth labels |  | ✓ |
| `ml.groundtruths.rules.*` | Full access to ground truth rules |  | ✓ |
| `ml_workflows_jobs.*` | Full access to ML workflow jobs | ✓ |  |
| `ml_workflows_jobs.execute.inference` | Run ML inference jobs |  | ✓ |
| `ml_workflows_jobs.read.*` | Read ML workflow jobs |  | ✓ |
| `ner.*` | Full access to named entity recognition resources | ✓ |  |
| `ner.*.read.*` | Read named entity recognition resources |  | ✓ |
| `notes.*` | Full access to notes | ✓ | ✓ |
| `pipeline_sections.*` | Full access to pipeline sections | ✓ | ✓ |
| `pipeline_workflows.*` | Full access to pipeline workflows | ✓ |  |
| `pipeline_workflows.read.*` | Read pipeline workflows |  | ✓ |
| `previews.*` | Full access to item previews | ✓ |  |
| `previews.read.*` | Read item previews |  | ✓ |
| `projects.read.*` | Read project metadata | ✓ | ✓ |
| `projects.write.*` | Modify project metadata | ✓ |  |
| `savedsearches.*` | Full access to saved searches (create, read, modify, delete) | ✓ | ✓ |
| `scores.*` | Full access to scores | ✓ |  |
| `scores.read.*` | Read scores |  | ✓ |
| `signals.*` | Full access to signals | ✓ |  |
| `signals.read.*` | Read signals |  | ✓ |
| `sources.*` | Full access to data sources | ✓ |  |
| `sources.read.*` | Read data sources |  | ✓ |
| `synonyms.read.*` | Read synonym configurations | ✓ | ✓ |

## Server Role Permissions

The table below lists the permissions granted to each server-level (tenant) role.

| Permission | Description | Admin | User | Reader |
| --- | --- | --- | --- | --- |
| `admin` | Full server administrator privileges | ✓ |  |  |
| `admin_space` | Access to the Server administration space in the UI | ✓ | ✓ |  |
| `profile.write.update` | Update own account profile and settings | ✓ | ✓ |  |
| `projects.write.create` | Create new projects | ✓ | ✓ |  |
| `reader` | Read-only (Restricted) server access |  |  | ✓ |
| `user` | Standard user server access |  | ✓ |  |
| `workspaces.create` | Create new workspaces | ✓ | ✓ |  |
| `workspaces.delete` | Delete workspaces | ✓ |  |  |