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

# Alcances clave API

> Permisos de números de teléfono virtuales: consultar y configurar voz entrante.

Cada **alcance** desbloquea un tipo de operación de número virtual. Conceda solo lo que su integración necesita.

## Cómo enviar la clave

**Recomendado**

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

**Alternativo**

```http theme={null}
x-api-key: sk_live_su_clave_aqui
```

<Info>
  Cada clave API pertenece a **un** espacio de trabajo. No puede acceder a otro espacio de trabajo con la misma clave.
</Info>

## Combinaciones comunes

<CardGroup cols={2}>
  <Card title="Solo consultar" icon="magnifying-glass">
    `phone_numbers:read`
  </Card>

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

  <Card title="Solo configurar entrante" icon="phone-arrow-down-left">
    `phone_numbers:update`
  </Card>

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

<Warning>
  Lista de alcances **vacía** al crear = acceso **ADMIN** (todo). En producción, restrija siempre.
</Warning>

<Note>
  **La compra** de un número se realiza en el **panel**. La API consulta números disponibles, lista números del espacio de trabajo y configura voz entrante.
</Note>

## Alcances disponibles

<AccordionGroup>
  <Accordion title="phone_numbers:read">
    * Listar números contratados del espacio de trabajo (`GET /v1/phone-numbers`)
    * Obtener un número por id (`GET /v1/phone-numbers/:id`)
    * Buscar números disponibles antes de pagar en el panel (`GET /v1/phone-numbers/available`)
  </Accordion>

  <Accordion title="phone_numbers:update">
    Actualizar configuración de un número (`PATCH /v1/phone-numbers/:id`): etiqueta, acción de voz entrante (`inboundVoiceAction`), desvío, TTS, grabación, etc.
  </Accordion>
</AccordionGroup>

## Relación con la API de Voz

Para **iniciar** llamadas con el número, use alcances de voz (`voice:call`, `voice:read`, …). Los alcances de esta página aplican **solo** a **`/v1/phone-numbers`**.

## Errores de autenticación

<AccordionGroup>
  <Accordion title="401: clave ausente, inválida o revocada">
    Verifique `Authorization: Bearer sk_...` y que la clave no se haya eliminado en el panel.
  </Accordion>

  <Accordion title="403: alcance ausente">
    Confirme que la clave tiene `phone_numbers:read` o `phone_numbers:update` para la ruta.
  </Accordion>
</AccordionGroup>

## Próximos pasos

* [Inicio rápido](/es/phone-numbers-api/como-funciona/quick-start)
* [API de Voz, inicio rápido](/es/voice-api/como-funciona/quick-start)
* [Guía de claves API](/es/guides/api-key/index)