# Scopes

Each Cherry API endpoint requires a specific scope. A key's granted scopes are listed in [`GET /me`](https://portal.cherry.fun/docs/api/authentication.md). Calling an endpoint without its scope returns `403 INSUFFICIENT_SCOPE`.

## Scopes come in two classes

Scopes are keyed to the surface they authorize, so they attach to the matching key type:

- **Project keys** (`cherry_sk_`) hold **Apps-API** scopes: `groups:*`, `members:*`, `messages:*`. They manage rooms, members, and messages the project owns.
- **Bot keys** (`cherry_bot_`) hold **`bots:*`** scopes: DMs, group posts, interactive messages, and in-room moderation as the bot.

Granting an Apps-API scope to a bot key (or vice-versa) has no effect: the scope only unlocks endpoints on its own surface.

## Apps API scopes (project keys)

| Scope | Grants | Endpoints |
|---|---|---|
| `groups:create` | Create rooms | `POST /apps/groups` |
| `groups:manage` | Read / update / delete your rooms | `GET /apps/groups`, `GET /apps/groups/:id`, `PATCH /apps/groups/:id`, `DELETE /apps/groups/:id` |
| `members:invite` | Invite members | `POST /apps/groups/:id/members` |
| `members:moderate` | Kick / ban / mute / set roles in rooms the project owns | `.../members/:wallet`, `.../ban`, `.../unban`, `.../mute`, `.../unmute`, `.../role` |
| `messages:send` | Send messages as the app bot | `POST /apps/groups/:id/messages` |
| `messages:read` | Read messages | `GET /apps/groups/:id/messages` |
| `messages:delete` | Delete messages | `DELETE /apps/groups/:id/messages/:messageId` |

## Bot API scopes (bot keys)

| Scope | Grants | Endpoints |
|---|---|---|
| `bots:dm:send` | Send DMs as the bot | `POST /bots/sendDirectMessage` |
| `bots:dm:read` | Read DM history | `GET /bots/getDirectChat` |
| `bots:groups:send` | Post messages into groups | `POST /bots/sendGroupMessage` |
| `bots:groups:moderate` | Ban / kick / mute / delete messages **as the bot**, in rooms where the bot holds a role | `POST /bots/banGroupMember`, `.../unbanGroupMember`, `.../kickGroupMember`, `.../muteGroupMember`, `.../unmuteGroupMember`, `.../deleteGroupMessage` |
| `bots:interactive` | Inline buttons & keyboards | `POST /bots/sendInteractiveMessage` |
| `bots:updates:poll` | Long-poll updates (Telegram-style) | `GET /bots/getUpdates` |
| `bots:webhook:manage` | Configure a webhook for updates | `POST /bots/setWebhook`, `.../deleteWebhook` |
| `bots:callback:answer` | Respond to inline button presses | `POST /bots/answerCallbackQuery` |
| `messages:edit` | Edit previously sent messages | `POST /bots/editMessageText`, `.../editMessageReplyMarkup` |

> **Note:** `bots:groups:moderate` lets the bot **call** the moderation endpoints. Whether a given action succeeds still depends on the bot's **role in the room** - see [Members & moderation](https://portal.cherry.fun/docs/api/members.md). Signing scopes (`bots:sign:request`, `bots:tx:request`) require admin review before they take effect.

## Granting scopes to a key

Every scope above except the review-gated signing scopes is **self-serve**: you grant it yourself, no approval needed.

- **In the portal:** open the key's scope picker (project keys under your project's **API keys** section, bot keys under the bot's **Keys** section), tick the scopes, and save.
- **Programmatically** (from an authenticated portal session), `PATCH` the key with the full scope set you want it to have (this replaces, not appends):

  ```http
  PATCH /api/v1/projects/:projectId/api-keys/:keyId          # a project key
  PATCH /api/v1/projects/:projectId/bots/:botId/keys/:keyId  # a bot key
  Content-Type: application/json
  ```

  ```json
  { "scopes": ["messages:read", "messages:send", "members:moderate"] }
  ```

> **Tip:** Grant only the scopes a key needs. A read-only feed needs just `messages:read`; a moderation bot needs `bots:groups:moderate` (plus its role in the room).

## Next steps

- [Members & moderation](https://portal.cherry.fun/docs/api/members.md) · [Rate limits & errors](https://portal.cherry.fun/docs/api/rate-limits.md) · [Endpoint reference](https://portal.cherry.fun/docs/api/reference.md)