Authentication & Permissions

API Keys

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

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/...`

# 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, recordings, 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)
`read:support_tickets`	Enterprise support tickets; available only to `enterprise_all_teams` keys

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. The support-ticket feed additionally requires read:support_tickets.
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.

Getting Started

Endpoints

Webhooks and Lead Intake

Custom Integration

ServiceTitan Technical Reference

Security and Reliability

API Keys

Obtaining API Keys

Key Types

Permissions

Multi-team Behavior

​API Keys

​Obtaining API Keys

​Key Types

​Permissions

​Multi-team Behavior

API Keys

Obtaining API Keys

Key Types

Permissions

Multi-team Behavior