> ## 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 Push: apps, dispositivos, envio e consulta.

<Tip>
  Cada escopo é uma **porta** na sua chave: app, registro de device, envio ou leitura, abra só o necessário.
</Tip>

Cada **escopo** libera um tipo de operação no Push. Use só o que sua integração precisa.

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

## Combinações comuns

<CardGroup cols={2}>
  <Card title="Só enviar" icon="paper-plane">
    `push:send`
  </Card>

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

  <Card title="Setup completo Web" icon="globe">
    `push:apps:manage`, `push:devices:register`, `push:send`, `push:read`
  </Card>

  <Card title="Só registrar devices" icon="mobile">
    `push:devices:register`
  </Card>
</CardGroup>

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

## Escopos disponíveis

<AccordionGroup>
  <Accordion title="push:apps:read">
    Listar e consultar Push Apps do workspace.
  </Accordion>

  <Accordion title="push:apps:manage">
    Criar, atualizar (VAPID, FCM, APNs conforme produto) e remover Push Apps.
  </Accordion>

  <Accordion title="push:devices:register">
    Registrar dispositivo ou subscription. Também usado para remover dispositivo.
  </Accordion>

  <Accordion title="push:send">
    Enviar notificação imediata ou agendada para até 100 device IDs por requisição.
  </Accordion>

  <Accordion title="push:read">
    * Listar e consultar envios
    * Listar e consultar dispositivos
    * Cancelar push agendado (status `SCHEDULED`)
  </Accordion>
</AccordionGroup>

## Limite por app

Se a chave tiver **`pushAppIds`** configurados, ela só envia para dispositivos daqueles apps. Device de app fora da lista → **403** (`PUSH_APP_NOT_ALLOWED`).

Lista vazia = qualquer app do workspace.

## Erros comuns

<AccordionGroup>
  <Accordion title="401: chave ausente, inválida ou revogada">
    Confira `Authorization: Bearer sk_...` e se a chave não foi apagada no painel.
  </Accordion>

  <Accordion title="403: sem escopo ou app não permitido">
    Verifique escopo da operação, `pushAppIds` na chave e origem permitida no app (`ORIGIN_NOT_ALLOWED` no registro público).
  </Accordion>

  <Accordion title="402/403: créditos ou agendamento">
    Envio exige crédito (`PLAN_LIMIT_CREDITS`). Agendamento depende do plano (`PLAN_LIMIT_SCHEDULING`).
  </Accordion>
</AccordionGroup>

## Próximos passos

* [Quick Start](/push-api/como-funciona/quick-start)
* [Eventos dos webhooks](/push-api/como-funciona/eventos-do-webhooks)
* [Chaves de API (guia)](/guides/api-key/index)