Authentication

API Keys

Partner API v2 authenticates with a per-agency Bearer access token. Create named keys under Integrations → API Keys. Each key can include one or more scopes, or * for full agency access:

• * - Full access (all agency Partner API scopes)
• calendar - Availability and create bookings
• appointments - List, update, cancel appointments; booking widgets; hours
• analytics - Path catalog (thin list) and Path Analytics reports
• contacts - Contact CRM read/write, tags, restore
• messages - Inbox, notes, and read state
• paths - Path builder CRUD, publish, and history
• fields - Custom field definitions (delete archives)
• lead-orders - Lead order list, pause/resume, cancel, patch
• voice-ai - Voice AI calls and wallet balance
• users - Agency members, invites, and roles
• settings - Curated agency and agent settings (no OAuth secrets)

Authorization: Bearer bp_...

Creating a key returns two secrets (each shown once):

• Access token (bp_...) - use on every API request. Expires 30 days after create or renew.
• Rotate key (bpr_...) - one-time secret used only to renew. After a successful renew it is burned and a new rotate key is returned.

Store the rotate key separately from the access token (for example app env vs secrets manager). Secrets are stored hashed; you can revoke or edit scopes later from the dashboard.

Access token expiry

When an access token expires, Partner API calls return 401 with code: "token_expired". Renew with the unused rotate key before continuing - same pattern as OAuth 2.0 (access on every request; refresh only at the token endpoint).

Renew requires both the current access token (valid or expired) and the unused rotate key. A successful renew returns a new access token and a new one-time rotate key - persist both immediately. The docs Try it panel stores both and auto-refreshes once on token_expired.

curl -s -X POST https://benefitpath.com/api/v2/auth/token/renew \
  -H "Content-Type: application/json" \
  -d '{
    "access_token": "bp_...",
    "rotate_key": "bpr_..."
  }' | jq

If you lose the access token or the unused rotate key, use Integrations → API Keys → Rotate secrets (or Regenerate rotate key) in the agency dashboard. There is no Partner API recovery without those secrets.

Where to get a token

• Agency dashboard - Integrations → API Keys (owners and admins).
• Legacy Calendar API token - older single tokens still work and imply full partner scopes (no 30-day expiry). Prefer new API Keys for new integrations.

Treat every token like a password. Renewing, rotating, or revoking immediately invalidates the previous values.

Request rules

• Send Authorization: Bearer ... on every request (except POST /api/v2/auth/token/renew).
• Use Content-Type: application/json for POST/PATCH/PUT bodies.
• Missing or invalid tokens return 401.
• Expired access tokens return 401 with code: "token_expired".
• A valid token without the needed scope returns 403 (for example Token missing required scope: contacts).
• Responses are always limited to the agency that owns the token.
• GET /api/v2/paths accepts either paths or analytics (analytics returns a thinner catalog).
• OpenAPI: GET /api/v2/openapi.json (no auth required for the document itself).

Browse endpoint docs from Resources.

Optional team member targeting

When creating calendar bookings or querying availability, you may pass an optional team member with query params or JSON body fields: agent_uuid (aliases: agentUuid, user_uuid, user, agent). The member must belong to the agency.