Skip to content

Authentication and scopes

  1. In Settings → Integrations → API & webhooks, a workspace admin or owner creates a key, gives it a name and selects its scopes.
  2. The key is shown only once. Store it in the secret vault of the server that calls the API.
  3. Send it with every request:
Authorization: Bearer pf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  • It belongs to one workspace. Every call acts on that workspace; nothing in the body or the URL changes that.
  • It can only do what its scopes allow (table below).
  • Once revoked, it stops working immediately. It is also revoked automatically when the person who created it is no longer a workspace admin.
  • Available on paid plans (and for clients funded by their agency). On the Free plan and on Try, the key responds plan_upgrade_required; once you subscribe, the same key works again.
  • It is for server-to-server use. Never put the key in your website, your mobile app or any code that runs on your customer’s machine.

Check your key with GET /v1/me (Quickstart).

Scope Allows
whatsapp:read Read lines, templates, the 24-hour window, messages and media
whatsapp:send Send WhatsApp messages and upload files
leads:read Look up leads and read their timeline
leads:write Create leads
accounts:read Read accounts, stages, owners and funnels
meetings:read Read meetings
cadences:read List cadences
cadences:write Enroll a lead in a cadence and stop the lead’s cadence
webhooks:manage Create and manage webhooks

A route outside the key’s scopes responds 403 insufficient_scope, with the missing scope in details.required_scope, before anything happens. In the API reference, each route shows the scope it requires (x-required-scope).

  • JSON in UTF-8. Send Content-Type: application/json on requests with a body.
  • Ids are UUIDs. Dates are ISO-8601, in UTC. Phone numbers are E.164 (+5511999998888).
  • Every response includes X-Request-Id. Give this value to support.
  • Bodies up to 1 MB.