> ## Documentation Index
> Fetch the complete documentation index at: https://docs.drime.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Scopes

> What each permission opens, and what no application can have

A scope is written `{resource}.{read|write}`, and a `.write` scope always includes its `.read`. A `GET` or `HEAD` request needs the `.read` scope of its resource, any other method needs the `.write` one.

Ask only for what your application calls. Users see every scope on the authorization screen, in the words of the second column, and they can untick them.

## Available scopes

| Scope | On the authorization screen | Routes under `/api/v1` |
| - | - | - |
| `files.read` / `files.write` | See your files / Create and edit files | `file-entries…`, `drive/…`, `uploads…`, `s3/…`, `tus/…`, `file-versions…`, `file-versioning…`, `file-backup…`, `backups/…`, `entry/…`, `videos/…`, `stream/…`, `albums…`, `playlists…`, `comments/…`, `file-activities…`, `devices…`, `device-backups…`, `getEditor/…`, `createDoc`, `createSheet`, `createSlide`, `createWebShortcut` |
| `folders.read` / `folders.write` | See your folders / Create and organise folders | `folders…`, `folder/…`, `drive/folders/…`, `users/{id}/folders` |
| `sharing.read` / `sharing.write` | See your shared links / Share on your behalf | `file-entries/{id}/share`, `file-entries/{id}/unshare`, `file-entries/{id}/change-permissions`, `file-entries/{id}/shareable-link`, `file-entries/{id}/restrictions…`, `shareable-links…`, `drive/file-entries/{id}/email-recipients…` |
| `file_requests.read` / `file_requests.write` | See your file requests / Manage your file requests | `file-requests…` |
| `tags.read` / `tags.write` | See your tags / Manage your tags | `tags…`, `file-entry-tags…`, `file-entries/{id}/sync-tags` |
| `workspaces.read` / `workspaces.write` | See your workspaces / Manage your workspaces | `workspace…`, `me/workspaces`, `me/workspace-permissions`, `me/workspace/personal…` |
| `sign.read` / `sign.write` | See your signature requests / Manage signature requests | `sign/…` |
| `whiteboards.read` / `whiteboards.write` | See your whiteboards / Edit your whiteboards | `whiteboards…`, `whiteboard/…` |
| `track.read` / `track.write` | See your tracked sends / Manage tracked sends | `track/…` |
| `contacts.read` / `contacts.write` | See your contacts / Manage your contacts | `contacts…` |
| `analytics.read` | See your usage statistics | `user/space-usage…`, `user/storage-breakdown` |
| `notifications.read` | See your notifications | `notifications…` |

A route written with `…` covers everything that starts with it. The sharing and tag routes on a file entry are matched before the broad `file-entries…` line, so sharing a file needs `sharing.write`, not `files.write`.

## Exceptions to the method rule

* `POST /file-entries/download-urls`, `POST /file-entries/sync-info` and `POST /file-entries/hash/check` only read: `files.read` is enough.
* `GET /workspace/join/…` joins a workspace: it needs `workspaces.write`.
* `analytics.read` and `notifications.read` have no `.write` counterpart. Marking notifications as read or deleting them is not available to applications.

## The sync API

The sync API (`/api/v1/sync/…`) mirrors the whole Drive tree, files and folders together, so it asks for both:

| Route | Scopes needed |
| - | - |
| `POST /sync/batch` | `files.write` **and** `folders.write` |
| Every other `/sync/…` route | `files.read` **and** `folders.read` |

It is not available to an application that works in [its own folder](/oauth/app-folder), whatever its scopes.

## Every token can read

`GET /users/me`, whatever its scopes. Use it to learn which account authorized you, and to check that a token still works.

## What no application can have

* **`*`.** There is no "everything" scope. Ask for what you use.
* **`vault.read` and `vault.write`.** The Drime Vault is end-to-end encrypted and only Drime's own apps can access it. This includes the Vault's folder tree, `users/{id}/folders?vault=1`.
* **`workspaces.*`**, for an application that works in [its own folder](/oauth/app-folder): that folder lives in the user's personal Drive.

## Always refused

Whatever its scopes, a token never reaches the routes that manage the account itself: API tokens and sessions, e-mail address, password and two-factor settings, the sign-in routes, billing, settings, the admin area, the developer console and the OAuth endpoints. An application cannot create another token or widen its own access.

A route that belongs to no resource above is refused too.

## When a scope is missing

```json theme={null}
{
  "message": "This API key is missing the required scope: folders.write"
}
```

The status is `403`. Tick the scope under **Permissions** in the console, then send your users through the [authorization flow](/oauth/authorization-flow) again: a token never gains a scope after it was issued. The **Analytics** tab of your application counts these refusals by scope.

A route that is always refused answers `403` with:

```json theme={null}
{
  "message": "This endpoint cannot be accessed with a restricted API key."
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.