# 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](/en/developers/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 in `details.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:

```http
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.