> ## 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 de números virtuais: consultar e configurar voz de entrada.

Cada **escopo** libera um tipo de operação em números virtuais. 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ó consultar" icon="magnifying-glass">
    `phone_numbers:read`
  </Card>

  <Card title="Consultar e configurar" icon="sliders">
    `phone_numbers:read`, `phone_numbers:update`
  </Card>

  <Card title="Só configurar entrada" icon="phone-arrow-down-left">
    `phone_numbers:update`
  </Card>

  <Card title="Fluxo completo" icon="list-check">
    `phone_numbers:read`, `phone_numbers:update`
  </Card>
</CardGroup>

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

<Note>
  **Contratar** (comprar) um número é pelo **painel**. A API consulta disponíveis, lista os do workspace e configura voz de entrada.
</Note>

## Escopos disponíveis

<AccordionGroup>
  <Accordion title="phone_numbers:read">
    * Listar números contratados do workspace (`GET /v1/phone-numbers`)
    * Consultar um número pelo id (`GET /v1/phone-numbers/:id`)
    * Buscar números disponíveis antes do checkout no painel (`GET /v1/phone-numbers/available`)
  </Accordion>

  <Accordion title="phone_numbers:update">
    Atualizar configuração de um número (`PATCH /v1/phone-numbers/:id`): rótulo, ação de voz de entrada (`inboundVoiceAction`), encaminhamento, TTS, gravação, etc.
  </Accordion>
</AccordionGroup>

## Relação com a Voice API

Para **originar** chamadas com o número, use escopos de Voz (`voice:call`, `voice:read`, …). Os escopos desta página valem **apenas** para **`/v1/phone-numbers`**.

## Erros de autenticação

<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">
    Verifique se a chave tem `phone_numbers:read` ou `phone_numbers:update` conforme a rota.
  </Accordion>
</AccordionGroup>

## Próximos passos

* [Quick Start](/phone-numbers-api/como-funciona/quick-start)
* [Voice API, Quick Start](/voice-api/como-funciona/quick-start)
* [Chaves de API (guia)](/guides/api-key/index)