> ## 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 del canal de voz: originar, consultar, controlar sesión y descargar grabaciones.

<Tip>
  Cada alcance es una **puerta** en su clave: marque, consulte o controle la sesión. Abra solo lo que necesite.
</Tip>

Cada **alcance** desbloquea un tipo de operación de voz. Use 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 marcador simple" icon="phone">
    `voice:call`, `voice:read`
  </Card>

  <Card title="IVR en tiempo real" icon="headset">
    `voice:call`, `voice:read`, `voice:control`
  </Card>

  <Card title="Solo consultar historial" icon="clock-rotate-left">
    `voice:read`
  </Card>

  <Card title="Grabaciones" icon="microphone">
    `voice:read` (descarga de grabación)
  </Card>
</CardGroup>

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

## Alcances disponibles

<AccordionGroup>
  <Accordion title="voice:call">
    Originar llamadas salientes. Requiere número **ACTIVO** y saldo o créditos. Respuesta típica: **202** con `id` de la llamada.
  </Accordion>

  <Accordion title="voice:read">
    Listar llamadas del espacio de trabajo, consultar detalles y eventos (`includeEvents`) y descargar archivos de grabación.
  </Accordion>

  <Accordion title="voice:control">
    Acciones en sesión activa: `speak`, `play`, `gather`, `transfer`, `record-start`, `record-stop`, `dtmf`, `hangup`.
  </Accordion>
</AccordionGroup>

## Errores comunes

<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="402: saldo o créditos insuficientes">
    Espacio de trabajo bloqueado o sin saldo para marcar. Resuelva en el panel.
  </Accordion>

  <Accordion title="403: alcance ausente">
    Verifique el alcance de la operación (`Missing scope: voice:call`, etc.).
  </Accordion>

  <Accordion title="400: origen inválido o no ACTIVO">
    `from` debe ser un número del espacio de trabajo **ACTIVO** (id o E.164).
  </Accordion>
</AccordionGroup>

## Próximos pasos

* [Inicio rápido](/es/voice-api/como-funciona/quick-start)
* [Introducción](/es/voice-api/como-funciona/introducao)
* [Eventos de webhook](/es/voice-api/como-funciona/eventos-do-webhooks)
* [Claves API (guía)](/es/guides/api-key/index)