Authentication and scopes
- In Settings → Integrations → API & webhooks, a workspace admin or owner creates a key, gives it a name and selects its scopes.
- The key is shown only once. Store it in the secret vault of the server that calls the API.
- Send it with every request:
Authorization: Bearer pf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxKey rules
Section titled “Key rules”- 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).
Scopes
Section titled “Scopes”| 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).
Conventions
Section titled “Conventions”- JSON in UTF-8. Send
Content-Type: application/jsonon 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.