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

# Authentication & Permissions

> API key types, team scoping, and permission scopes

## API Keys

All Enterprise API requests are authenticated with an API key in the `Authorization` header:

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

Keys follow the format `avoca_<64 hex characters>` — the `avoca_` prefix followed by a cryptographically random hex token. Keys are stored hashed; treat them like passwords and never commit them to source control.

### Obtaining API Keys

API keys are managed in the Avoca dashboard:

* **Team-level keys:** `Settings → API Keys` on your team (`/team/[slug]/settings/api-keys`)
* **Enterprise-level keys:** `Settings → API Keys` on your enterprise (`/enterprise/[slug]/settings/api-keys`)

Only teams with enterprise access can generate API keys.

## Key Types

| Type                   | Access                                          | Team scoping                                                                                                                              |
| ---------------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `enterprise`           | Single team                                     | Locked to one team; no `x-team-id` header needed                                                                                          |
| `enterprise_all_teams` | All teams in the enterprise                     | v0 endpoints require `x-team-id` header or `team_id` query param (except `GET /api/teams`); v1 endpoints take the team ID in the URL path |
| `portfolio_all_teams`  | All teams in a portfolio (can span enterprises) | Same scoping rules as `enterprise_all_teams`; not valid for enterprise-scoped routes like `/api/v1/enterprise/...`                        |

```bash theme={null}
# Single-team key
curl -H "Authorization: Bearer $API_KEY" \
  "https://enterprise-api.avoca.ai/api/calls"

# Multi-team key on a v0 endpoint (requires x-team-id)
curl -H "Authorization: Bearer $API_KEY" -H "x-team-id: 808" \
  "https://enterprise-api.avoca.ai/api/calls"

# Multi-team key on a v1 endpoint (team in path)
curl -H "Authorization: Bearer $API_KEY" \
  "https://enterprise-api.avoca.ai/api/v1/teams/808/sessions"
```

## Permissions

Each key is configured with permission scopes controlling which endpoints it can call. Calling an endpoint without the required permission returns `403 Forbidden`.

| Permission                 | Grants access to                                                                        |
| -------------------------- | --------------------------------------------------------------------------------------- |
| `read:calls`               | Call records, metadata, and pre-call transfers                                          |
| `read:transcripts`         | Call transcripts                                                                        |
| `read:leads`               | Unified leads (v0) and the canonical leads feed (v1)                                    |
| `read:teams`               | Listing accessible teams (multi-team keys)                                              |
| `read:coach`               | Coach call evaluations, scores, and rubrics                                             |
| `read:scheduler_analytics` | Simple Scheduler analytics, sessions, bookings, booking requests, and scheduler configs |
| `read:outbound`            | Outbound texting feeds (campaign texts and subscription events)                         |

## Multi-team Behavior

* Cross-team v1 endpoints (`/api/v1/sessions`, `/api/v1/bookings`, `/api/v1/analytics/funnel`) aggregate across all teams the key can access, with an optional `team_id` query filter.
* Enterprise-scoped routes (`/api/v1/enterprise/:enterpriseId/...`) require an `enterprise_all_teams` key whose enterprise matches the path.
* Designated internal QA/test teams are excluded from multi-team aggregations by default; pass `include_test_teams=true` to include them. Explicitly team-addressed requests are never filtered.