Keys and scopes
Create a key
In Settings › API, an administrator creates the key and chooses:
- Name: the system that will use it (e.g. "Company ERP").
- Environment: Production acts for real; Test simulates everything (Test mode).
- What the key may do: the scopes below. A call outside the key's scopes returns
403 insufficient_scope, with the scopes that work indetails.required. - Start campaigns without waiting for approval: without it, this key's campaigns follow the company's approval rule (the budget always applies).
- Valid until and only from these IP addresses, optional.
The whole key is shown only once, when created. Keep it like a password. Production keys start with dt_live_, test keys with dt_test_.
Authenticate
Send the key on every call:
Authorization: Bearer dt_live_...Authorization: ApiKey dt_live_... works too. The company comes from the address (/v1/c/{company}/...) and must be the key's.
Scopes
| Group | Scope | What it allows |
|---|---|---|
| Campaigns | campaigns:read | See campaigns and results |
| Campaigns | campaigns:write | Create and edit drafts |
| Campaigns | campaigns:send | Start, pause and cancel |
| Contacts | contacts:read | See contacts and their field values |
| Contacts | contacts:write | Create and update contacts |
| Contacts | fields:read | See the list of fields |
| Contacts | fields:write | Create fields |
| Contacts | contacts:delete | Erase contacts' data (LGPD) |
| Templates | templates:read | See templates |
| Templates | templates:write | Create templates and submit them to Meta |
| Messages and conversations | messages:send_template | Send templates |
| Messages and conversations | messages:send_text | Send text and files (24-hour window) |
| Messages and conversations | conversations:read | See conversations and messages |
| Messages and conversations | conversations:write | Close and reopen conversations |
| Flows and scheduling | flows:start | Start flows |
| Flows and scheduling | appointments:read | See appointments |
| Flows and scheduling | appointments:write | Book, move and cancel appointments |
| Other | webhooks:manage | Manage webhooks |
| Other | reports:read | See reports and costs |
| Other | workspace:read | See numbers, teams and tags |
| Other | integrations:outboundpro | Connect OutboundPro Conversas |
Older keys
Keys made before scopes (dsf_live_...) keep working with the integration access they had. Choosing scopes for one of them limits it to those.
Security
- One key per system, with the fewest scopes.
- If a key leaks, revoke it in Settings › API: it stops at once.
- Creating, editing and revoking are recorded in the Audit log, with who did it.