Перейти к основному содержанию
Ключ выпускается на экранах платформы: Платформа → Ключи API → Выпустить ключ. Вы называете ключ, выбираете компании и права, при необходимости задаёте потолок трат и срок. Ключ целиком показывается один раз, сразу после выпуска. Выпустить ключ может владелец или администратор организации. Остальным раздел закрыт, на экране написано «Нет доступа». По самому ключу API ключи не выпускаются и не меняются, это делает только человек в кабинете.

​
Выпустить ключ

1

Откройте «Ключи API»

В меню кабинета нажмите Платформа, выберите раздел Ключи API и нажмите Выпустить ключ. Откроется окно «Новый ключ».
2

Назовите ключ

В поле «Название» напишите, где ключ будет использоваться, например «Интеграция с CRM». По названию вы потом найдёте ключ в списке и в расходе.
3

Выберите компании и права

На шаге «Доступ» оставьте «Все компании организации» или отметьте нужные компании. В блоке «Что можно этим ключом» поставьте галочки прав.
4

Задайте потолок, срок и адреса

На шаге «Потолок и срок» три необязательных поля: «Потолок трат за месяц», «Действует до» и «Разрешённые адреса». Пустой потолок значит «без потолка», пустой срок значит срок по умолчанию, пустой список адресов значит «с любых».
5

Скопируйте ключ

После выпуска в поле «Полный ключ» показан ключ целиком. Нажмите Скопировать и сохраните его в хранилище секретов своего сервера. Второй раз ключ не показывается.
Если после выпуска экран показал предупреждение, ключ создан, но запросы к ИИ-бухгалтеру по нему пока не пройдут. Обычная причина — пустой баланс платформы: см. Баланс платформы и расход. Ключей в организации может быть ограниченное число. Выключенные ключи тоже считаются. Когда предел достигнут, выпуск отвечает ошибкой с кодом api_keys_limit: отзовите ненужные ключи.

​
Права и компании

Ключ действует от имени того, кто его выпустил, и никогда не шире его прав. Каждое право в каждой компании проверяется по правам этого человека. Если он перестал быть владельцем или администратором организации, ключ перестаёт работать, пока его не передадут другому. Прав семь. В запросах и ответах API они называются так, как указано в начале каждой строки.
  • company.read — «Читать данные компаний». Есть у каждого ключа.
  • chat.use — «Работать с ИИ-бухгалтером». Вопросы и задания ИИ, оплачиваются с баланса платформы.
  • proposals.create — «Готовить документы для 1С». ИИ-бухгалтер готовит документ, человек потом одобряет.
  • proposals.approve — «Одобрять документы и записывать в 1С». Ключ сам записывает документы в 1С, выдавайте это право осторожно.
  • automations.read — «Смотреть автоматизации». Сценарии, хуки и запуски, только просмотр.
  • automations.manage — «Управлять автоматизациями». Создавать, менять и запускать сценарии.
  • webhooks.manage — «Управлять вебхуками». Доступно только ключу на все компании, потому что события приходят по всей организации.
Ключ на все компании видит и будущие компании, но только те, где состоит человек, выпустивший ключ. В каждой компании ключ может не больше, чем позволяет роль этого человека в ней. Поле «Разрешённые адреса» ограничивает, откуда ключ принимает запросы. В нём перечисляют IP-адреса и подсети через запятую. Запрос с другого адреса получит отказ 403 с кодом ip_not_allowed. Компании, права и срок действующего ключа меняет только тот, кто его выпустил: меню ключа, пункт Изменить. Другой администратор может только сузить ключ: снизить потолок или сократить список адресов.

​
Срок действия

Срок есть у каждого ключа. Если поле «Действует до» оставить пустым, действует срок по умолчанию, сейчас это 90 дней. За 14 и за 3 дня до конца срока автор ключа получает письмо, а на адреса вебхуков уходит событие api_key.expiring. Пока ключ действует, его срок можно продлить или сократить через «Изменить». Истёкший ключ продлить нельзя: иначе снова заработал бы старый секрет. Чтобы вернуть истёкший ключ в работу, перевыпустите его. Права, компании и потолок сохранятся, срок начнётся заново, а секрет будет новый.

​
Выключить, перевыпустить, передать, отозвать

Все действия находятся в меню ключа в списке. Пункт Выключить останавливает ключ сразу и обратимо. Запросы по нему получают отказ 401 с кодом key_disabled. Секрет, права и срок не меняются. Сценарии автоматизаций, сохранённые этим ключом, не запускаются, пока он выключен. Выключить ключ может любой владелец или администратор, а включить обратно — только автор ключа или владелец организации. Пункт Перевыпустить выдаёт новый секрет для того же ключа. Новый ключ целиком показывается один раз, как при выпуске. Прежний секрет ещё какое-то время работает, чтобы ваша программа успела переключиться: до какого момента, написано в строке «Прежний секрет работает до». Повторный перевыпуск гасит прежний секрет сразу. Перевыпустить ключ может только его автор. Пункт Передать нужен, когда автор ключа уходит, а интеграция остаётся. Ключ начинает действовать от имени другого владельца или администратора организации. Секрет и срок остаются прежними. Передать можно только тому, чьих прав в компаниях ключа хватает на права ключа.
Пункт Отозвать выключает ключ навсегда, вернуть его нельзя. Программам с этим ключом понадобится новый. Сценарии автоматизаций, сохранённые отозванным ключом, выключаются вместе с ним.
Если ключ мог попасть к посторонним, отзовите его или сразу выключите, а потом разберитесь. Журнал запросов по ключу лежит в разделе «Журнал запросов», кто и что менял — в разделе «Журнал действий». Владелец организации может запретить ключи целиком: настройка «Разрешить ключи API» в настройках организации. Если её выключить, новые ключи выпустить нельзя, а действующие сразу перестают работать.

​
Что дальше