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

# Scopes

> Understand API key permissions and scopes

## Overview

Scopes define what operations an API key can perform. When creating an API key, you assign specific scopes to limit its access to only the resources it needs.

<Tip>
  **Principle of least privilege:** Always assign the minimum scopes required for your integration to function.
</Tip>

## Available Scopes

### Contacts

| Scope            | Description                         |
| ---------------- | ----------------------------------- |
| `contacts:read`  | List and retrieve contact details   |
| `contacts:write` | Create, update, and delete contacts |
| `contacts:*`     | All contact permissions             |

**Endpoints:**

* `GET /api/v1/contacts` - requires `contacts:read`
* `POST /api/v1/contacts` - requires `contacts:write`
* `GET /api/v1/contacts/:id` - requires `contacts:read`
* `PATCH /api/v1/contacts/:id` - requires `contacts:write`
* `DELETE /api/v1/contacts/:id` - requires `contacts:write`

### Surveys

| Scope           | Description                        |
| --------------- | ---------------------------------- |
| `surveys:read`  | List and retrieve survey details   |
| `surveys:write` | Create, update, and delete surveys |
| `surveys:send`  | Trigger survey sends to contacts   |
| `surveys:*`     | All survey permissions             |

**Endpoints:**

* `GET /api/v1/surveys` - requires `surveys:read`
* `POST /api/v1/surveys` - requires `surveys:write`
* `GET /api/v1/surveys/:id` - requires `surveys:read`
* `PATCH /api/v1/surveys/:id` - requires `surveys:write`
* `DELETE /api/v1/surveys/:id` - requires `surveys:write`

### Sequences

| Scope               | Description                        |
| ------------------- | ---------------------------------- |
| `sequences:read`    | List and retrieve sequence details |
| `sequences:execute` | Trigger sequences for contacts     |
| `sequences:*`       | All sequence permissions           |

**Endpoints:**

* `GET /api/v1/sequences` - requires `sequences:read`
* `GET /api/v1/sequences/:id` - requires `sequences:read`
* `POST /api/v1/sequences/:id/execute` - requires `sequences:execute`

### Responses

| Scope            | Description                        |
| ---------------- | ---------------------------------- |
| `responses:read` | List and retrieve survey responses |
| `responses:*`    | All response permissions           |

**Endpoints:**

* `GET /api/v1/responses` - requires `responses:read`
* `GET /api/v1/responses/:id` - requires `responses:read`

### Reviews

| Scope           | Description                        |
| --------------- | ---------------------------------- |
| `reviews:read`  | List and retrieve customer reviews |
| `reviews:write` | Create and update review replies   |
| `reviews:*`     | All review permissions             |

**Endpoints:**

* `GET /api/v1/reviews` - requires `reviews:read`
* `GET /api/v1/reviews/:id` - requires `reviews:read`
* `POST /api/v1/reviews/:id/reply` - requires `reviews:write`
* `PATCH /api/v1/reviews/:id/reply` - requires `reviews:write`

### Webhooks

| Scope            | Description                              |
| ---------------- | ---------------------------------------- |
| `webhooks:read`  | List and retrieve webhook configurations |
| `webhooks:write` | Create, update, and delete webhooks      |
| `webhooks:*`     | All webhook permissions                  |

### Admin

| Scope   | Description                                      |
| ------- | ------------------------------------------------ |
| `admin` | **Full access** to all resources (use sparingly) |

<Warning>
  The `admin` scope grants unrestricted access to your entire organization's data. Only use this for internal tools or trusted integrations.
</Warning>

## Wildcard Scopes

You can use wildcards to grant all permissions for a resource:

* `contacts:*` - All contact operations (read + write)
* `surveys:*` - All survey operations (read + write + send)
* `sequences:*` - All sequence operations (read + execute)

## Scope Checking

When an API key doesn't have the required scope, you'll receive:

**Status:** `403 Forbidden`

```json theme={null}
{
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "This API key does not have the required scope: contacts:write",
    "requiredScope": "contacts:write",
    "availableScopes": ["contacts:read", "surveys:read"]
  }
}
```

## Common Scope Combinations

<AccordionGroup>
  <Accordion title="Read-only analytics integration">
    For dashboards that display metrics but don't modify data:

    ```json theme={null}
    ["responses:read", "reviews:read", "contacts:read"]
    ```
  </Accordion>

  <Accordion title="CRM sync integration">
    For two-way contact synchronization with your CRM:

    ```json theme={null}
    ["contacts:read", "contacts:write", "responses:read"]
    ```
  </Accordion>

  <Accordion title="Marketing automation">
    For triggering surveys and sequences based on customer actions:

    ```json theme={null}
    ["contacts:write", "sequences:execute", "responses:read"]
    ```
  </Accordion>

  <Accordion title="Review management tool">
    For monitoring and responding to customer reviews:

    ```json theme={null}
    ["reviews:read", "reviews:write"]
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/authentication">
    Learn how to create API keys
  </Card>

  <Card title="Quick Start" icon="rocket" href="/guides/quickstart">
    Make your first API call
  </Card>
</CardGroup>