> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pickupbell.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Scopes

> Every scope PickupBell understands, what it authorizes, and what it does NOT.

A token's scope set is fixed at creation. You don't edit scopes after the fact — rotate by issuing a new key.

## Locations

| Scope             | What it authorizes                                     |
| ----------------- | ------------------------------------------------------ |
| `locations:read`  | List + fetch locations, read subscription status       |
| `locations:write` | Update location identity fields (name, industry, etc.) |

## Team

| Scope          | What it authorizes                           |
| -------------- | -------------------------------------------- |
| `members:read` | List location members (emails masked on API) |

## Calls

| Scope              | What it authorizes                                                                                      |
| ------------------ | ------------------------------------------------------------------------------------------------------- |
| `calls:read`       | List + fetch call rows (caller phone masked)                                                            |
| `calls:write`      | Reserved — calls are inserted by the voice-provider webhook only                                        |
| `transcripts:read` | **Unmask transcript text.** Without this, `transcript` is `null` even on a call you can read otherwise. |
| `recordings:read`  | **Unmask recording URL.** Same rule as transcripts.                                                     |

## Leads

| Scope         | What it authorizes                                      |
| ------------- | ------------------------------------------------------- |
| `leads:read`  | List + fetch leads                                      |
| `leads:write` | Create leads manually, update status / assignee / notes |

## Bookings

| Scope            | What it authorizes                                 |
| ---------------- | -------------------------------------------------- |
| `bookings:read`  | List + fetch bookings                              |
| `bookings:write` | Create/update bookings (back-office, integrations) |

## Insights

| Scope           | What it authorizes                                          |
| --------------- | ----------------------------------------------------------- |
| `insights:read` | Rolled-up metrics (calls answered, revenue recovered, etc.) |

## Agent & FAQs

| Scope         | What it authorizes                                    |
| ------------- | ----------------------------------------------------- |
| `agent:read`  | Read agent config + business hours + call forwarding  |
| `agent:write` | Update agent config, hours, forwarding, notifications |
| `faqs:read`   | List FAQs + pricebook                                 |
| `faqs:write`  | Create/update/delete FAQs + pricebook items           |

## Webhooks

| Scope            | What it authorizes                                        |
| ---------------- | --------------------------------------------------------- |
| `webhooks:admin` | Reserved for future outbound-webhook management endpoints |

## API keys

| Scope           | What it authorizes               |
| --------------- | -------------------------------- |
| `api_keys:read` | List keys (prefix + scopes only) |

## Never exposed via API keys

Regardless of scope, API tokens can **never**:

* read billing-provider customer or subscription identifiers
* access billing management endpoints (upgrades, invoices, payment methods)
* invite team members
* mint or revoke API keys
* access another location's data
* view plaintext API-key secrets (only prefixes)

These controls are enforced in the service layer, not just the REST adapter — the MCP server gets the same restrictions.