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

# API Key Scopes

> Voice channel permissions: originate, query, control session, and download recordings.

<Tip>
  Each scope is a **door** on your key: dial, query, or control the session, open only what you need.
</Tip>

Each **scope** unlocks one type of Voice operation. Use only what your integration needs.

## How to send the key

**Recommended**

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

**Alternative**

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

<Info>
  The API Key belongs to **one** workspace. You cannot access another workspace with the same key.
</Info>

## Common combinations

<CardGroup cols={2}>
  <Card title="Simple dialer only" icon="phone">
    `voice:call`, `voice:read`
  </Card>

  <Card title="Real-time IVR" icon="headset">
    `voice:call`, `voice:read`, `voice:control`
  </Card>

  <Card title="Query history only" icon="clock-rotate-left">
    `voice:read`
  </Card>

  <Card title="Recordings" icon="microphone">
    `voice:read` (recording download)
  </Card>
</CardGroup>

<Warning>
  An **empty** scope list on create = **ADMIN** access. Always restrict in production.
</Warning>

## Available scopes

<AccordionGroup>
  <Accordion title="voice:call">
    Originate outbound calls. Requires **ACTIVE** number and balance or credits. Typical return: **202** with call `id`.
  </Accordion>

  <Accordion title="voice:read">
    List workspace calls, query detail and events (`includeEvents`), and download recording files.
  </Accordion>

  <Accordion title="voice:control">
    Actions on active session: `speak`, `play`, `gather`, `transfer`, `record-start`, `record-stop`, `dtmf`, `hangup`.
  </Accordion>
</AccordionGroup>

## Common errors

<AccordionGroup>
  <Accordion title="401: missing, invalid, or revoked key">
    Check `Authorization: Bearer sk_...` and that the key was not deleted in the dashboard.
  </Accordion>

  <Accordion title="402: insufficient balance or credits">
    Workspace blocked or no balance for dialing. Resolve in the dashboard.
  </Accordion>

  <Accordion title="403: missing scope">
    Verify scope for the operation (`Missing scope: voice:call`, etc.).
  </Accordion>

  <Accordion title="400: invalid or non-ACTIVE origin">
    `from` must be an **ACTIVE** workspace number (id or E.164).
  </Accordion>
</AccordionGroup>

## Next steps

* [Quick Start](/en/voice-api/como-funciona/quick-start)
* [Introduction](/en/voice-api/como-funciona/introducao)
* [Webhook events](/en/voice-api/como-funciona/eventos-do-webhooks)
* [API Keys (guide)](/en/guides/api-key/index)