> For the complete documentation index, see [llms.txt](https://docs.verida.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.verida.ai/getting-started/scopes.md).

# Scopes

Verida provides a robust and granular permission model to control access to user data and APIs. This document summarizes **all available scopes**, how they are organized, and how to use them in your application.

### Scope Types

There are three main categories of scopes:

1. **API Scopes** (`api:`)
   * Provide access to specific Verida API endpoints (e.g., LLM prompts, universal search).
2. **Database Scopes** (`db:`)
   * Grant read, write, and delete access to a **specific database** within Verida.
3. **Datastore Scopes** (`ds:`)
   * Grant read, write, and delete access to a **specific datastore** (structured data) within Verida.

***

### 1. API Scopes

**API scopes** provide access to particular operations or specialized APIs within the Verida ecosystem. These scopes have a number of **credits** that are consumed when these API endpoints are invoked.

Below is a breakdown by functionality:

#### 1.1 AI Scopes

* **`api:llm-prompt`**\
  Allows running a Large Language Model (LLM) prompt **without** access to user data.
* **`api:llm-agent-prompt`**\
  Allows running a Large Language Model **agent** prompt **with** access to user data.
* **`api:llm-profile-prompt`**\
  Allows running an LLM prompt to generate a profile **based on user data**.

#### 1.2 Search Scopes

* **`api:search-universal`**\
  Perform a keyword-based search **across all user data**.
* **`api:search-ds`**\
  Perform a keyword-based search **across a specific datastore**.
* **`api:search-chat-threads`**\
  Perform a keyword-based search **across all chat threads**.

#### 1.3 Database Operations (API Endpoint)

* **`api:db-get-by-id`**
  * **Endpoint:** `GET /db/$dbName/$id`
  * Allows retrieving a record by ID from a **specific database**.
* **`api:db-create`**
  * **Endpoint:** `POST /db/$dbName`
  * Allows creating a new record in a **specific database**.
* **`api:db-update`**
  * **Endpoint:** `PUT /db/$dbName/$id`
  * Allows updating an existing record in a **specific database**.
* **`api:db-query`**
  * **Endpoint:** `POST /db/query/$dbName`
  * Allows querying a **specific database**.

#### 1.4 Datastore Operations (API Endpoint)

* **`api:ds-get-by-id`**
  * **Endpoint:** `GET /ds/$dsUrlEncoded/$id`
  * Retrieve a record by ID from a **specific datastore**.
* **`api:ds-create`**
  * **Endpoint:** `POST /ds/$dsUrlEncoded`
  * Create a new record in a **specific datastore**.
* **`api:ds-update`**
  * **Endpoint:** `PUT /ds/$dsUrlEncoded/$id`
  * Update an existing record in a **specific datastore**.
* **`api:ds-query`**
  * **Endpoints:**
    * `POST /ds/query/$dsUrlEncoded` (query a datastore)
    * `GET /ds/watch/$dsUrlEncoded` (subscribe to datastore changes)
  * Query or watch a **specific datastore**.
* **`api:ds-delete`**
  * **Endpoint:** `DELETE /ds/$dsUrlEncoded/$id`
  * Delete a record from a **specific datastore**.

***

### 2. Database Scopes (`db:`)

When requesting database-level access, your application must specify the permission type and the database name. The permissions are:

* **`r`**: Read-only
* **`rw`**: Read and write
* **`rwd`**: Read, write, and delete

A typical database scope looks like:

```
cssCopydb:{permission}:{databaseName}
```

For example:

* **`db:r:file`**
  * **Read-only** access to the `file` database.
* **`db:rw:file`**
  * **Read and write** access to the `file` database.
* **`db:rwd:file`**
  * **Read, write, and delete** access to the `file` database.

> **Note**: The `dbName` often corresponds to an internal Verida database identifier (e.g., `file`), but it can vary depending on the specific database you want to access.

***

### 3. Datastore Scopes (`ds:`)

Similar to databases, **datastore scopes** define the level of access to structured data by referencing a **schema URL** (or a **short-hand** for common schemas). Permissions mirror database scopes:

* **`r`**: Read-only
* **`rw`**: Read and write
* **`rwd`**: Read, write, and delete

#### 3.1 Datastore Scope Format

```
ds:{permission}:{base64EncodedSchemaUrl}
```

where:

* `base64EncodedSchemaUrl` is the base64-encoded URL of the datastore schema, or a **short-hand** if it’s a well-known schema.

For example, the **Files** datastore schema:

```
https://common.schemas.verida.io/file/v0.1.0/schema.json
```

Base64-encoded, it might look like:

```
aHR0cHM6Ly9jb21tb24uc2NoZW1hcy52ZXJpZGEuaW8vZmlsZS92MC4xLjAvc2NoZW1hLmpzb24=
```

Hence, read-only scope for that datastore:

```
ds:r:base64/aHR0cHM6Ly9jb21tb24uc2NoZW1hcy52ZXJpZGEuaW8vZmlsZS92MC4xLjAvc2NoZW1hLmpzb24=
```

> **Tip**: You can generate base64 values using:
>
> * `btoa()` in the browser
> * `Buffer.from("http://...").toString("base64")` in Node/TypeScript

#### 3.2 Datastore Shortcuts

Verida provides **short-hand** references for commonly used datastores. In these cases, you can simply specify the short name instead of the base64-encoded URL. For instance:

| Shortcut              | Description                                   |
| --------------------- | --------------------------------------------- |
| `social-following`    | Social media following (e.g., Facebook pages) |
| `social-post`         | Social media posts                            |
| `social-email`        | Emails                                        |
| `favourite`           | Favourites (e.g., liked videos, bookmarks)    |
| `file`                | Files (e.g., documents)                       |
| `social-chat-group`   | Chat groups (e.g., Telegram groups)           |
| `social-chat-message` | Chat messages (e.g., Telegram messages)       |
| `social-calendar`     | Calendars (e.g., Personal Google Calendar)    |
| `social-event`        | Calendar events (e.g., Meeting with Jane)     |

**Examples with Shortcuts**

* **`ds:r:file`**\
  Read-only access to the **Files** datastore.
* **`ds:rw:social-following`**\
  Read and write access to the **Social Following** datastore.
* **`ds:rwd:social-event`**\
  Read, write, and delete access to the **Social Event** datastore.

***

### Complete Scope List

Below is a combined list of all scopes you may encounter or request:

#### API Scopes

1. **LLM Scopes**
   * `api:llm-prompt`
   * `api:llm-agent-prompt`
   * `api:llm-profile-prompt`
2. **Search Scopes**
   * `api:search-universal`
   * `api:search-ds`
   * `api:search-chat-threads`
3. **Database API**
   * `api:db-get-by-id`
   * `api:db-create`
   * `api:db-update`
   * `api:db-query`
4. **Datastore API**
   * `api:ds-get-by-id`
   * `api:ds-create`
   * `api:ds-update`
   * `api:ds-query`
   * `api:ds-delete`

#### Database Scopes (`db:`)

* **`db:r:{databaseName}`**
* **`db:rw:{databaseName}`**
* **`db:rwd:{databaseName}`**

Examples:

* `db:r:file`
* `db:rw:file`
* `db:rwd:file`

#### Datastore Scopes (`ds:`)

* **`ds:r:{datastoreShortcutOrBase64Url}`**
* **`ds:rw:{datastoreShortcutOrBase64Url}`**
* **`ds:rwd:{datastoreShortcutOrBase64Url}`**

Common shortcuts include:

* `social-following`, `social-post`, `social-email`, `favourite`, `file`, `social-chat-group`, `social-chat-message`, `social-calendar`, `social-event`

Examples:

* `ds:r:file`
* `ds:rw:social-post`
* `ds:rwd:social-event`
* `ds:r:base64/aHR0cHM6Ly9jb21tb24u...` (if using a custom schema URL)

***

### Usage and Best Practices

1. **Request Only Needed Scopes**
   * Align the scopes with the data and endpoints your application genuinely requires. Minimizing scopes reduces security risks and simplifies user acceptance.
2. **Explain Scopes to Users**
   * Provide a clear explanation during the consent flow about why you need each scope. This transparency fosters trust.
3. **Store Tokens Securely**
   * Whether you are using a database or localStorage, always handle tokens and granted scopes in a secure manner.
4. **Check for Scope Changes**
   * The Verida ecosystem may add or update scopes. Always verify the latest scope list from the [Scopes API](https://api.verida.ai/api/rest/v1/auth/scopes) or developer documentation.

***

### Further Resources

* **Scopes API**:\
  <https://api.verida.ai/api/rest/v1/auth/scopes>\
  Fetch a real-time list of valid scopes, including new or updated scopes.
* **Developer Console**:\
  [https://admin.verida.ai/](#scope-types)\
  An easy to use interface to generate authorization requests and use APIs.
* **Verida GitHub**:\
  <https://github.com/verida/>\
  Explore sample applications and open-source libraries.

***

By combining these scopes effectively, you can harness the power of Verida’s decentralized data ecosystem while respecting user consent and data security.&#x20;


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.verida.ai/getting-started/scopes.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.