API-ключи
API-ключ позволяет сайту, приложению или вашему серверу работать с проектом без входа в интерфейс: отправлять события, читать профили, управлять сегментами, цепочками и рассылками. Ключи создаются и отзываются в разделе «Настройки» → «API-ключи».
Раздел видят «Владелец», «Администратор» и «Менеджер». Создавать и отзывать ключи могут «Владелец» и «Администратор».
Типы ключей
| Write | Secret | |
|---|---|---|
| Начинается с | cdp_wk_ |
cdp_sk_ |
| Что разрешает | только отправку событий | отправку событий и действия в проекте по выбранным правам |
| Где использовать | код сайта, мобильное приложение, сервер | только ваш сервер |
| Можно показывать посторонним | да, он виден в коде страниц сайта | нет, храните в секрете |
| Лимит запросов | 6000 в минуту | 1200 в минуту (по умолчанию) |
Write-ключ публичный по своей природе: он стоит в коде каждой страницы сайта. С ним можно только отправлять события, поэтому утечка не открывает доступ к данным. Чтобы чужой сайт не мог отправлять события от вашего имени, в разделе «Сайт» можно указать домены, с которых ключ принимается — см. Подключение сайта.
Secret-ключ даёт серверный доступ к данным проекта. Никогда не вставляйте его в код страниц, мобильные приложения и публичные репозитории.
Как создать ключ
- Откройте «API-ключи».
- В карточке «Новый ключ» введите «Название» — по нему вы потом поймёте, где ключ используется, например «Сайт» или «Сервер интернет-магазина».
- Выберите «Тип»: Write или Secret.
- Для Secret отметьте «Права ключа» — только то, что действительно нужно интеграции.
- Нажмите «Создать ключ».
Сразу после создания вверху страницы появится полный ключ. Нажмите «Копировать» и сохраните его, например в менеджере паролей или в переменных окружения сервера. Секретный ключ показывается только один раз: мы храним лишь его отпечаток, восстановить ключ нельзя. Если вы его потеряли, создайте новый и отзовите старый.
Write-ключ для сайта удобнее создавать прямо в разделе «Сайт»: там он сразу подставляется в код установки и доступен в любой момент — см. Подключение сайта.
В таблице ключей видны название, кто и когда его создал, тип, начало ключа (например, cdp_sk_a1b2…), количество прав и время последнего использования.
Права секретного ключа
Выдать ключу можно только права, которые есть у вас самих. Права действуют на весь проект — ограничить ключ отдельными цепочками или сегментами нельзя.
| Право | Что открывает |
|---|---|
| Чтение профилей | профиль по идентификатору и его события |
| Персональные данные без маскирования | email, телефон и другие личные данные в открытом виде; без этого права они маскируются |
| Изменение профилей и согласий | согласия на рассылки, привязка Telegram |
| Удаление профилей (GDPR) | удаление профиля по запросу покупателя |
| Каталог событий и трейтов | список событий и свойств профилей |
| Чтение / изменение сегментов | просмотр, создание, изменение, удаление и пересчёт сегментов |
| Чтение цепочек и отчётов; изменение черновиков и вход участников; публикация, пауза и архив цепочек | работа с цепочками |
| Чтение рассылок и отчётов; создание и изменение; запуск, пауза и отмена | работа с рассылками |
| Чтение каталога товаров и рекомендаций; загрузка и удаление товаров | товары и рекомендации |
| Аналитика | отчёты |
Пример: ключу для синхронизации VIP-покупателей из CRM достаточно прав «Чтение сегментов» и «Изменение сегментов».
Все действия, выполненные через секретный ключ, записываются в аудит-лог проекта от имени ключа — см. Настройки проекта, тариф и аудит.
Как отозвать ключ
- Найдите ключ в таблице и нажмите «Отозвать».
- Подтвердите действие.
Запросы с этим ключом сразу перестанут работать (ответ 401). Отозванный ключ остаётся в списке с пометкой «Отозван», чтобы было видно его историю. Вернуть его нельзя — при необходимости создайте новый.
Отзывайте ключ сразу, если он мог попасть к посторонним, если сотрудник с доступом к нему уволился или если интеграция больше не используется.
Что важно знать
- Лимиты. При превышении лимита запросов или месячной квоты событий тарифа API отвечает
429. Распределяйте отправку равномерно и повторяйте запрос с паузой. - Безопасная замена ключа. Создайте новый ключ, обновите его на сервере, убедитесь, что запросы идут (поле «Использовался»), и только потом отзовите старый.
- Отдельный ключ на каждую интеграцию. Так в аудит-логе видно, кто что сделал, а при утечке достаточно отозвать один ключ.
- Как отправлять события и вызывать API с сервера, читайте в статье Интеграция с сервера.