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

> Quais permissões sua chave precisa para conectar, enviar e gerenciar Telegram no Notifique.

<Tip>
  A **API Key** é o cartão de acesso: cada **escopo** abre uma porta. Em produção, libere só o que sua integração precisa.
</Tip>

## Em poucas palavras

* Escopos `telegram:*` cobrem instâncias, envio, leitura e edição.
* O campo **`instanceIds`** restringe **quais conexões** a chave pode usar.
* Guia geral: [Chaves de API](/guides/api-key/index). Conexão: [Quick Start](/telegram-api/como-funciona/quick-start).

***

## Como enviar a chave

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

Alternativa: `x-api-key: sk_live_xxxxx`.

<Warning>
  Escopos **vazios** na criação = acesso **ADMIN** (tudo). Em produção, restrinja sempre.
</Warning>

***

## Combinações prontas

<CardGroup cols={2}>
  <Card title="Bot básico" icon="robot">
    `telegram:instances:create`, `telegram:instances:list`, `telegram:send`
  </Card>

  <Card title="Enviar e consultar" icon="magnifying-glass">
    `telegram:send`, `telegram:read`
  </Card>

  <Card title="Com cancelamento" icon="clock">
    `telegram:send`, `telegram:cancel`
  </Card>

  <Card title="Fluxo completo" icon="list-check">
    `telegram:send`, `telegram:read`, `telegram:cancel`, `telegram:update`, `telegram:delete`
  </Card>
</CardGroup>

***

## Escopos disponíveis

<AccordionGroup>
  <Accordion title="telegram:instances:list">
    Listar conexões, ver detalhes e QR (modo USER).
  </Accordion>

  <Accordion title="telegram:instances:create">
    Criar bot com token ou iniciar conta USER (login por QR ou sessão).
  </Accordion>

  <Accordion title="telegram:instances:delete">
    Remover conexão.
  </Accordion>

  <Accordion title="telegram:send">
    Enviar texto, mídia por URL HTTPS e localização (modo bot).
  </Accordion>

  <Accordion title="telegram:read">
    Histórico de enviadas, lista de chats e inbound.
  </Accordion>

  <Accordion title="telegram:cancel">
    Cancelar na fila ou agendada.
  </Accordion>

  <Accordion title="telegram:update">
    Editar texto enviado.
  </Accordion>

  <Accordion title="telegram:delete">
    Apagar mensagem no chat.
  </Accordion>
</AccordionGroup>

***

## Limitar por conexão (`instanceIds`)

Além do escopo (o **que**), `instanceIds` define **onde**:

| Situação                         | Resultado                                     |
| -------------------------------- | --------------------------------------------- |
| Envio em instância fora da lista | **403**                                       |
| Lista vazia / omitida            | Todas as instâncias do workspace (com escopo) |

***

## Erros comuns

| HTTP / `code`                           | O que fazer                             |
| --------------------------------------- | --------------------------------------- |
| **401** `UNAUTHORIZED`                  | Confira `Authorization: Bearer sk_...`  |
| **403** escopo ausente                  | Inclua o escopo da rota na chave        |
| **403** instância fora de `instanceIds` | Ajuste a lista na chave                 |
| `TELEGRAM_BOT_TOKEN_INVALID`            | Token do BotFather inválido na criação  |
| `TELEGRAM_USER_TERMS_REQUIRED`          | Modo USER exige `acceptUserTerms: true` |

Catálogo completo: [Respostas de erro](/guides/conceitos/resposta-de-erros).

***

## Próximos passos

* [Quick Start](/telegram-api/como-funciona/quick-start)
* [Eventos dos webhooks](/telegram-api/como-funciona/eventos-do-webhooks)
* [Modos de conexão](/telegram-api/como-funciona/modos-de-conexao)