> ## 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 Voz: originar, consultar, controlar sessão e baixar gravações.

<Tip>
  Cada escopo é uma **porta** na sua chave: discar, consultar ou controlar a sessão, abra só o necessário.
</Tip>

Cada **escopo** libera um tipo de operação em Voz. 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ó discador simples" icon="phone">
    `voice:call`, `voice:read`
  </Card>

  <Card title="URA em tempo real" icon="headset">
    `voice:call`, `voice:read`, `voice:control`
  </Card>

  <Card title="Só consultar histórico" icon="clock-rotate-left">
    `voice:read`
  </Card>

  <Card title="Gravações" icon="microphone">
    `voice:read` (download de gravação)
  </Card>
</CardGroup>

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

## Escopos disponíveis

<AccordionGroup>
  <Accordion title="voice:call">
    Originar chamadas de saída. Exige número **ACTIVE** e saldo ou créditos. Retorno típico: **202** com `id` da chamada.
  </Accordion>

  <Accordion title="voice:read">
    Listar chamadas do workspace, consultar detalhe e eventos (`includeEvents`) e baixar arquivo de gravação.
  </Accordion>

  <Accordion title="voice:control">
    Ações em sessão ativa: `speak`, `play`, `gather`, `transfer`, `record-start`, `record-stop`, `dtmf`, `hangup`.
  </Accordion>
</AccordionGroup>

## 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="402: saldo ou créditos insuficientes">
    Workspace bloqueado ou sem saldo para discagem. Regularize no painel.
  </Accordion>

  <Accordion title="403: sem escopo">
    Verifique escopo da operação (`Missing scope: voice:call`, etc.).
  </Accordion>

  <Accordion title="400: origem inválida ou não ACTIVE">
    O `from` precisa ser um número **ACTIVE** do workspace (id ou E.164).
  </Accordion>
</AccordionGroup>

## Próximos passos

* [Quick Start](/voice-api/como-funciona/quick-start)
* [Introdução](/voice-api/como-funciona/introducao)
* [Eventos dos webhooks](/voice-api/como-funciona/eventos-do-webhooks)
* [Chaves de API (guia)](/guides/api-key/index)