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

# API Key scopes

> Chat channel permissions: apps, users, conversations, and messages.

<Tip>
  Each scope is a **door** on your key: app, user, conversation, or message — open only what you need.
</Tip>

The **user JWT** does not use these scopes. It authenticates the client app on `/v1/chat/*` (REST) and the WebSocket. The API Key is for **your backend**.

## How to send the key

```http theme={null}
Authorization: Bearer sk_live_your_key_here
```

Or `x-api-key`. The key belongs to **one** workspace. Do not send `x-workspace-id` on v1.

## Common combinations

<CardGroup cols={2}>
  <Card title="App setup" icon="mobile">
    `chat:apps:create`, `chat:apps:manage`, `chat:apps:list`
  </Card>

  <Card title="Identity" icon="user">
    `chat:users`
  </Card>

  <Card title="Backend conversations" icon="comments">
    `chat:conversations:read`, `chat:conversations:write`
  </Card>

  <Card title="Messages" icon="paper-plane">
    `chat:messages:send`, `chat:messages:read`
  </Card>
</CardGroup>

<Warning>
  An **empty** scope list at creation = **ADMIN** access. Restrict in production.
</Warning>

## Available scopes

<AccordionGroup>
  <Accordion title="chat:apps:list">List and get Chat Apps.</Accordion>
  <Accordion title="chat:apps:create">Create a Chat App. The response includes the signing secret.</Accordion>
  <Accordion title="chat:apps:manage">Update name, origins, JWT flags, and **rotate** the secret.</Accordion>
  <Accordion title="chat:apps:delete">Remove a Chat App (soft delete).</Accordion>
  <Accordion title="chat:users">User upsert, JWT issue, and team agents.</Accordion>
  <Accordion title="chat:conversations:read">List and get workspace conversations.</Accordion>
  <Accordion title="chat:conversations:write">Create conversations, members, roles, join, and soft delete.</Accordion>
  <Accordion title="chat:messages:send">Send a message (1 `CHAT_MESSAGE` credit).</Accordion>
  <Accordion title="chat:messages:read">List messages and mark read.</Accordion>
  <Accordion title="chat:messages:delete">Soft-delete a message.</Accordion>
</AccordionGroup>

## JWT vs API Key

| Who     | Creates conversation (flags off)   | Sends message                | Lists conversations |
| ------- | ---------------------------------- | ---------------------------- | ------------------- |
| API Key | Yes                                | Yes (`senderExternalUserId`) | All in the app      |
| JWT     | No (`CHAT_CLIENT_CREATE_DISABLED`) | Yes, if a member             | Only the user's     |

## Common errors

* **401** — missing key/JWT, rotated secret, revoked `jti` (`CHAT_INVALID_TOKEN`)
* **403** — missing scope, origin not allowed, or JWT create with flags off (`CHAT_CLIENT_CREATE_DISABLED`)
* **402** — `WORKSPACE_BLOCKED`, `INSUFFICIENT_CREDITS`, or key spend limit
* **409** — `CHAT_DIRECT_EXISTS`

## Next steps

* [Quick Start](/en/chat-api/como-funciona/quick-start)
* [User and agent](/en/chat-api/como-funciona/usuario-e-agente)
* [Send messages](/en/chat-api/como-funciona/enviar-mensagens)
* [Webhook events](/en/chat-api/como-funciona/eventos-do-webhooks)
* [API keys guide](/en/guides/api-key/index)