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

> Which permissions your key needs to connect, send, and manage Telegram on Notifique.

<Tip>
  The **API Key** is your access card: each **scope** opens one door. In production, grant only what your integration needs.
</Tip>

## In brief

* `telegram:*` scopes cover instances, send, read, and edit.
* **`instanceIds`** restricts **which connections** the key can use.
* General guide: [API Keys](/en/guides/api-key/index). Connection: [Quick Start](/en/telegram-api/como-funciona/quick-start).

***

## How to send the key

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

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

<Warning>
  An **empty** scope list on create = **ADMIN** access (everything). Always restrict in production.
</Warning>

***

## Ready-made combinations

<CardGroup cols={2}>
  <Card title="Basic bot" icon="robot">
    `telegram:instances:create`, `telegram:instances:list`, `telegram:send`
  </Card>

  <Card title="Send and query" icon="magnifying-glass">
    `telegram:send`, `telegram:read`
  </Card>

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

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

***

## Available scopes

<AccordionGroup>
  <Accordion title="telegram:instances:list">
    List connections, view details, and QR (USER mode).
  </Accordion>

  <Accordion title="telegram:instances:create">
    Create bot with token or start USER account (QR or session login).
  </Accordion>

  <Accordion title="telegram:instances:delete">
    Remove connection.
  </Accordion>

  <Accordion title="telegram:send">
    Send text, media via HTTPS URL, and location (bot mode).
  </Accordion>

  <Accordion title="telegram:read">
    Sent history, chat list, and inbound.
  </Accordion>

  <Accordion title="telegram:cancel">
    Cancel queued or scheduled message.
  </Accordion>

  <Accordion title="telegram:update">
    Edit sent text.
  </Accordion>

  <Accordion title="telegram:delete">
    Delete message in chat.
  </Accordion>
</AccordionGroup>

***

## Restrict by connection (`instanceIds`)

Besides scope (the **what**), `instanceIds` defines **where**:

| Situation                         | Result                               |
| --------------------------------- | ------------------------------------ |
| Send on instance outside the list | **403**                              |
| Empty / omitted list              | All workspace instances (with scope) |

***

## Common errors

| HTTP / `code`                          | What to do                                 |
| -------------------------------------- | ------------------------------------------ |
| **401** `UNAUTHORIZED`                 | Check `Authorization: Bearer sk_...`       |
| **403** missing scope                  | Add the route scope to the key             |
| **403** instance outside `instanceIds` | Adjust the list on the key                 |
| `TELEGRAM_BOT_TOKEN_INVALID`           | Invalid BotFather token on create          |
| `TELEGRAM_USER_TERMS_REQUIRED`         | USER mode requires `acceptUserTerms: true` |

Full catalog: [Error responses](/en/guides/conceitos/resposta-de-erros).

***

## Next steps

* [Quick Start](/en/telegram-api/como-funciona/quick-start)
* [Webhook events](/en/telegram-api/como-funciona/eventos-do-webhooks)
* [Connection modes](/en/telegram-api/como-funciona/modos-de-conexao)