Ключи и права

Каждый запрос к API подписывается секретным ключом компании. Ключ выглядит так: dk_live_ и ещё 32 латинские буквы и цифры. Передавайте его в заголовке Authorization после слова Bearer:

curl https://api.ru.dialogi.io/v1/contacts \
  -H "Authorization: Bearer dk_live_…"

Ключ принимается только в этом заголовке. Без него, с неверным, истёкшим или отозванным ключом API отвечает 401 unauthenticated.

Где создать ключ

В личном кабинете: «Настройки» → «Разработчикам» → «Создать ключ». Раздел видят сотрудники с правом управлять API-ключами - по умолчанию это владелец и администратор компании.

• Ключ целиком показывают один раз, сразу после создания. Потом в списке видно только начало и последние четыре символа: dk_live_…a1b2. Потеряли ключ - перевыпустите его.
• В списке видно, когда ключ использовали последний раз.
• Ключ принадлежит компании, а не сотруднику. Он продолжит работать, если сотрудник, который его создал, уйдёт из компании.

API работает, пока у компании подключено дополнение «Публичный API» («Оплата» → «Тариф» → «Дополнительно»). Без него на любой запрос с рабочим ключом приходит 402 api-addon-required. Ключи можно создать заранее.

Храните ключ на сервере

Ключ открывает доступ к данным ваших клиентов. Не вставляйте его в код сайта, мобильного приложения или скрипта в браузере - оттуда его может забрать любой посетитель.

API намеренно не отвечает на запросы из браузера с других сайтов: заголовков CORS в ответах нет, и браузер такой запрос не отправит. Обращайтесь к API со своего сервера.

Если ключ попал в чужие руки, перевыпустите его с вариантом «Сразу» или отзовите.

Права

Права выдаются по разделам, отдельно на чтение и на запись:

Чтение - это получение списков и отдельных объектов. Запись - создание и изменение.

В окне создания ключа права выбираются так:

• Полный - чтение и запись во всех разделах.
• Только чтение - чтение во всех разделах, без записи.
• Выбрать - для каждого раздела: «Нет», «Чтение» или «Чтение и запись».

Права записываются в ключ при создании и потом не меняются. Нужен другой набор прав - создайте новый ключ, а старый отзовите.

Запрос, на который у ключа нет права, получает 403 forbidden. В detail указано, какого права не хватает:

{
  "type": "https://dialogi.io/errors/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "The API key lacks the contacts:write permission."
}

Проекты

Ключ работает со всеми проектами компании или только с выбранными.

• Все - все проекты компании, в том числе созданные позже.
• Выбрать - только отмеченные проекты. Удалённый проект выпадает из ключа сам.

Как это влияет на запросы:

• Список без project_id содержит данные всех проектов ключа. С project_id - только этого проекта.
• project_id проекта, которого нет в ключе, - ошибка 403 forbidden.
• Объект из проекта, которого нет в ключе, для этого ключа не существует: ответ 404 not-found.
• При создании контакта ключ с одним проектом подставит его сам. Если проектов у ключа несколько, передайте project_id в теле запроса, иначе будет 422 validation.

id проекта приходит в поле project_id каждого объекта - например, в списке контактов.

Перевыпуск

«Перевыпустить» в меню ключа создаёт новый ключ с тем же названием, правами и проектами. Старый продолжает работать столько, сколько вы выберете:

За это время замените ключ во всех своих системах. Пока старый ключ доживает свой срок, в списке у него написано, когда он перестанет работать. Перевыпустить такой ключ ещё раз нельзя - перевыпускайте новый.

Отзыв

«Отозвать» выключает ключ навсегда. Запросы с ним начнут получать 401 в течение 60 секунд. Отменить отзыв нельзя.

Только адреса /v1

Ключ работает только с адресами вида https://api.ru.dialogi.io/v1/.... Внутренний API личного кабинета ключ не принимает и отвечает ошибкой: это интерфейс для наших приложений, и он меняется без предупреждения.