Skip to main content

​
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

TypeAccessTeam scoping
enterpriseSingle teamLocked to one team; no x-team-id header needed
enterprise_all_teamsAll teams in the enterprisev0 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_teamsAll 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.
PermissionGrants access to
read:callsCall records, metadata, and pre-call transfers
read:transcriptsCall transcripts
read:leadsUnified leads (v0) and the canonical leads feed (v1)
read:teamsListing accessible teams (multi-team keys)
read:coachCoach call evaluations, scores, and rubrics
read:scheduler_analyticsSimple Scheduler analytics, sessions, bookings, booking requests, and scheduler configs
read:outboundOutbound 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.