# Cherry API: Authentication

The Cherry API is a REST API you call from **your backend** to manage Cherry chat programmatically: create rooms, send messages, and moderate members.

There are **two kinds of API key**, each a single opaque token you copy from [the portal](https://portal.cherry.fun/dashboard):

| Key | Format | Surface | Base URL |
|---|---|---|---|
| **Project key** | `cherry_sk_<projectId>_<secret>` | Apps API: manage rooms, members, and messages your **project** owns | `https://api.cherry.fun/api/v1/apps` |
| **Bot key** | `cherry_bot_<botId>_<secret>` | Bot API: act as a specific **bot** (DMs, group posts, in-room moderation) | `https://api.cherry.fun/api/v1/bots` |

> **Warning:** A key is a **secret**. Make these calls from your server only, never from the browser.

## The key is one opaque token

Copy the whole string from the portal and use it verbatim. Do **not** try to assemble it from an app ID plus a secret: the `<projectId>`/`<botId>` and `<secret>` are already baked into the single token you're shown.

> **Note:** The token is shown **once**, when you create it. Store it in your server's secrets. Lost it, or need to roll a secret you think is exposed? **Both project keys and bot keys** can be rotated in place (see below): rotation issues a fresh secret for the same key and invalidates the old one immediately.

```http
Authorization: Bearer cherry_sk_<projectId>_<secret>
```

```bash
# project key → Apps API
curl https://api.cherry.fun/api/v1/apps/me \
  -H "Authorization: Bearer cherry_sk_<projectId>_<secret>"

# bot key → Bot API
curl https://api.cherry.fun/api/v1/bots/me \
  -H "Authorization: Bearer cherry_bot_<botId>_<secret>"
```

> **Note:** `cha_<id>_<secret>` is a **deprecated legacy** format. Older tokens keep working during a migration grace window and resolve to a bot identity, but issue new keys as `cherry_sk_` / `cherry_bot_` and migrate off `cha_`.

## Which key do I use?

- **Project key** (`cherry_sk_`) - the classic server flow: create rooms, invite members, send/read/delete messages, and moderate rooms **your project owns** (the call acts as the room owner). Holds Apps-API scopes like `groups:*`, `members:*`, `messages:*`.
- **Bot key** (`cherry_bot_`) - for a named bot with its own wallet and identity: send DMs, post to groups, run interactive messages, and moderate rooms **where the bot itself holds a role**. Holds `bots:*` scopes.

The two models compose - see [Members & moderation](https://portal.cherry.fun/docs/api/members.md) and the [moderation bot guide](https://portal.cherry.fun/docs/guides/moderation-bot.md).

## Verify your credentials

`GET /me` on each surface returns that key's context, a quick way to confirm auth and see your granted scopes and bot wallet.

```http
GET /api/v1/apps/me    # with a project key
GET /api/v1/bots/me    # with a bot key
```

```json
{
  "appId": "550e8400-e29b-41d4-a716-446655440000",
  "scopes": ["groups:create", "members:invite", "messages:send"],
  "botWallet": "7jx8aB2c5DeF9hGhI1jK3lMnOpQ5rStUvWxYzAbCdEf",
  "rateLimits": { "perMinute": 600, "perDay": 50000 }
}
```

## Managing keys & scopes

Create, scope, and revoke keys in the portal: **project keys** under your project's **API keys** section, **bot keys** under the bot's **Keys** section. Each key carries its own scopes: grant only what that key needs. See [Scopes](https://portal.cherry.fun/docs/api/scopes.md) for the full list and how to grant them.

**Both key types** can also be **rotated** in place: project keys from your project's **API keys** section, bot keys from the bot's **Keys** section. Rotation issues a fresh secret for the same key (its id, name and scopes are preserved) and invalidates the old secret immediately, so reach for it when a secret may be exposed. Rotating a **revoked** key reactivates it with a new secret, so you can bring a key name back without re-granting its scopes.

```http
POST /api/v1/projects/:projectId/api-keys/:keyId/rotate           # rotate a project key in place
POST /api/v1/projects/:projectId/bots/:botId/keys/:keyId/rotate   # rotate a bot key in place
```

The response returns the new token once, exactly like key creation, copy it immediately.

## Next steps

- [Create rooms & attach to embeds](https://portal.cherry.fun/docs/api/rooms.md), the core dynamic-rooms flow.
- [Scopes](https://portal.cherry.fun/docs/api/scopes.md) · [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)