> ## 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.

# Escopos da API Key

> Permissões do canal Chat: apps, usuários, conversas e mensagens.

<Tip>
  Cada escopo é uma **porta** na sua chave: app, usuário, conversa ou mensagem — abra só o necessário.
</Tip>

O **JWT do usuário** não usa esses escopos. Ele autentica o app do cliente em `/v1/chat/*` (REST) e no WebSocket. A API Key é para o **seu backend**.

## Como enviar a chave

**Recomendado**

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

**Alternativo**

```http theme={null}
x-api-key: sk_live_sua_chave_aqui
```

<Info>
  A API Key pertence a **um** workspace. Você não acessa outro workspace com a mesma chave. Não envie `x-workspace-id` na v1.
</Info>

## Combinações comuns

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

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

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

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

<Warning>
  Lista de escopos **vazia** na criação = acesso **ADMIN**. Em produção, restrinja sempre.
</Warning>

## Escopos disponíveis

<AccordionGroup>
  <Accordion title="chat:apps:list">
    Listar e consultar Chat Apps do workspace.
  </Accordion>

  <Accordion title="chat:apps:create">
    Criar Chat App (`POST /v1/chat/apps`). A resposta inclui o signing secret.
  </Accordion>

  <Accordion title="chat:apps:manage">
    Atualizar nome, origens, flags JWT e **rotacionar** o secret.
  </Accordion>

  <Accordion title="chat:apps:delete">
    Remover Chat App (soft delete).
  </Accordion>

  <Accordion title="chat:users">
    Upsert de usuários, emissão de JWT e vínculo de agentes da equipe.
  </Accordion>

  <Accordion title="chat:conversations:read">
    Listar e obter conversas do workspace.
  </Accordion>

  <Accordion title="chat:conversations:write">
    Criar conversa, membros, papéis, join e exclusão lógica.
  </Accordion>

  <Accordion title="chat:messages:send">
    Enviar mensagem (1 crédito `CHAT_MESSAGE` por envio).
  </Accordion>

  <Accordion title="chat:messages:read">
    Listar mensagens e marcar leitura.
  </Accordion>

  <Accordion title="chat:messages:delete">
    Apagar mensagem (soft delete).
  </Accordion>
</AccordionGroup>

## JWT vs API Key

| Quem    | Cria conversa (flags off)           | Envia mensagem               | Lista as próprias conversas |
| ------- | ----------------------------------- | ---------------------------- | --------------------------- |
| API Key | Sim                                 | Sim (`senderExternalUserId`) | Todas do app                |
| JWT     | Não (`CHAT_CLIENT_CREATE_DISABLED`) | Sim, se for membro           | Só as do usuário            |

## Erros comuns

<AccordionGroup>
  <Accordion title="401: chave ou JWT inválido">
    Confira `Authorization: Bearer sk_...` ou o JWT (`iss` = `notifique-chat`, `aud` = Chat App). Token revogado ou secret rotacionado → `CHAT_INVALID_TOKEN`.
  </Accordion>

  <Accordion title="403: sem escopo ou cliente sem permissão">
    Escopo ausente na chave, origem fora de `allowedOrigins`, ou JWT tentando criar conversa com flags desligadas (`CHAT_CLIENT_CREATE_DISABLED`).
  </Accordion>

  <Accordion title="402: créditos, trial ou plano">
    Workspace bloqueado (`WORKSPACE_BLOCKED`), créditos insuficientes (`INSUFFICIENT_CREDITS`) ou limite de gasto da chave.
  </Accordion>

  <Accordion title="409: conversa 1:1 já existe">
    `CHAT_DIRECT_EXISTS` — o par de usuários já tem DIRECT. Use o id retornado na listagem.
  </Accordion>
</AccordionGroup>

## Próximos passos

* [Quick Start](/chat-api/como-funciona/quick-start)
* [Usuário e agente](/chat-api/como-funciona/usuario-e-agente)
* [Enviar mensagens](/chat-api/como-funciona/enviar-mensagens)
* [Eventos dos webhooks](/chat-api/como-funciona/eventos-do-webhooks)
* [Chaves de API (guia)](/guides/api-key/index)