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

# Scopes

> The read and write scopes that control what your app can access, and how to request them.

## What are Scopes?

Scopes are like permissions that control what your app can do when users connect it to their Fanvue account using OAuth 2.0. Think of them as specific access levels that determine which resources your application can read from or write to.

When you create your OAuth app, you'll specify which scopes you need based on what your app does. This ensures your application only has access to the data and features it actually needs, following the principle of least privilege for better security.

To learn more about OAuth 2.0 and how to set up your app, check out our [OAuth Tutorial](/authentication/overview).

## How Scopes Work

* **Permission Control**: Each scope grants access to specific resources and actions
* **Request Validation**: Every API request checks if your access token has the required scopes
* **Error Handling**: Requests without sufficient scopes return a `403 Forbidden` error
* **App Configuration**: Scopes are set when you create your OAuth app and determine what permissions users can grant

## Available Scopes

The following table lists all available scopes organized by resource:

| Resource       | Scopes                                        |
| -------------- | --------------------------------------------- |
| User           | `read:self`                                   |
| Chat           | `read:chat`, `write:chat`                     |
| Fan            | `read:fan`                                    |
| Creator        | `read:creator`, `write:creator`               |
| Media          | `read:media`, `write:media`                   |
| Posts          | `read:post`, `write:post`                     |
| Insights       | `read:insights`                               |
| Tracking Links | `read:tracking_links`, `write:tracking_links` |
| Agency         | `read:agency`, `write:agency`                 |

### Scope Descriptions

**`read:self`**\
Access your own user profile information, including basic account details and settings.

**`read:chat`**\
Read chat conversations, messages, and chat-related data. This includes viewing chat lists and message history.

**`write:chat`**\
Create new chats and send messages. This scope is required for any chat-related actions that modify data.

**`read:fan`**\
Access fan-related data and information within the platform.

**`read:creator`**
Access creator profiles, content, and creator-specific information.

**`write:creator`**
Modify creator profiles, settings, and creator-specific data.

**`read:media`**
Access media files, images, videos, and other content assets.

**`write:media`**
Upload, modify, and manage media files and content assets. Also required for vault folder management.

**`read:post`**
Read posts, including post details, comments, likes, and tips.

**`write:post`**
Create, edit, and manage posts and content on behalf of users.

**`read:insights`**
Access analytics, metrics, and insights data for performance tracking.

**`read:tracking_links`**
Read tracking links and the users associated with them, including per-user tracking metadata.

**`write:tracking_links`**
Create and delete tracking links.

**`read:agency`**
Read agency information, including the agency's team members.

**`write:agency`**
Manage agency team members and invites, including inviting new team members and creators.

## Setting Up Scopes

When creating your OAuth app, you'll configure which scopes your app can request:

1. **Choose the scopes** your app actually needs
2. **Follow the principle of least privilege** - only request what's necessary
3. **Consider your users** - they'll see what permissions you're asking for

Users will then grant (or deny) these specific permissions when they connect your app to their account. For the complete setup process, see our [OAuth Tutorial](/authentication/overview).

## Error Handling

If your access token doesn't have the required scopes for a request, you'll receive:

```json theme={null}
{
  "error": "Insufficient scopes"
}
```

This response comes with a `403 Forbidden` HTTP status code. Make sure your app requests all necessary scopes and that users have granted them.