Authentication

Bearer access tokens, rotate keys, scopes, and renew for Partner API v2.

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)
  • voice-ai - Voice AI agents, outbound calls, cancel, and wallet balance
  • users - Team 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_...) - the refresh token. Send it only to POST /api/v2/auth/token/renew when the access token expires. Each successful refresh returns a new access token and a new rotate key, and invalidates the previous rotate key. Persist both.

Store the rotate key separately from the access token. Secrets are stored hashed; you can revoke or edit scopes later from the dashboard.

Access token expiry

API calls send only Authorization: Bearer .... The rotate key is never sent to those endpoints.

When the access token expires, the call returns 401 with code: "token_expired". Refresh it at the token endpoint with the current access token and the unused rotate key. A successful refresh returns a new access token and a new rotate key. Persist both immediately. The previous rotate key no longer works.

Presenting a rotate key that was already used revokes the API key. Create a new key if that happens.

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 in the agency dashboard.

Where to get a token

  • Agency dashboard - Integrations → API Keys (owners and admins).
  • Legacy calendar tokens - older non-expiring tokens still authenticate if present, but new booking integrations should use API Keys.

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

Request rules

  • Send Authorization: Bearer ... on every API request. Do not send the rotate key.
  • 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". Refresh at POST /api/v2/auth/token/renew.
  • A valid token without the needed scope returns 403.