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

> Virtual phone number permissions: query and configure inbound voice.

Each **scope** unlocks one type of virtual number operation. Grant 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="Query only" icon="magnifying-glass">
    `phone_numbers:read`
  </Card>

  <Card title="Query and configure" icon="sliders">
    `phone_numbers:read`, `phone_numbers:update`
  </Card>

  <Card title="Configure inbound only" icon="phone-arrow-down-left">
    `phone_numbers:update`
  </Card>

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

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

<Note>
  **Purchasing** a number is done in the **dashboard**. The API queries available numbers, lists workspace numbers, and configures inbound voice.
</Note>

## Available scopes

<AccordionGroup>
  <Accordion title="phone_numbers:read">
    * List contracted workspace numbers (`GET /v1/phone-numbers`)
    * Get a number by id (`GET /v1/phone-numbers/:id`)
    * Search available numbers before dashboard checkout (`GET /v1/phone-numbers/available`)
  </Accordion>

  <Accordion title="phone_numbers:update">
    Update a number's configuration (`PATCH /v1/phone-numbers/:id`): label, inbound voice action (`inboundVoiceAction`), forwarding, TTS, recording, etc.
  </Accordion>
</AccordionGroup>

## Relationship with the Voice API

To **originate** calls with the number, use Voice scopes (`voice:call`, `voice:read`, …). Scopes on this page apply **only** to **`/v1/phone-numbers`**.

## Auth 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="403: missing scope">
    Confirm the key has `phone_numbers:read` or `phone_numbers:update` for the route.
  </Accordion>
</AccordionGroup>

## Next steps

* [Quick Start](/en/phone-numbers-api/como-funciona/quick-start)
* [Voice API, Quick Start](/en/voice-api/como-funciona/quick-start)
* [API keys guide](/en/guides/api-key/index)