Ключи API
Выберите личный или сервисный ключ, сохраните секрет при создании и заменяйте учётные данные, не теряя из виду клиентов, которые их используют.
Ключ API позволяет клиенту действовать с заданными правами. Права личного ключа зависят от членства и разрешений пользователя. Сервисный ключ принадлежит организации, поэтому уход коллеги не повлияет на автоматизацию. С RBAC сервисному ключу также можно назначить собственную роль и область доступа к ресурсам.
Секрет показывается при создании ключа. Позже восстановить его из записи ключа не получится. Сразу сохраните его в менеджере секретов или хранилище учётных данных, которое поддерживает клиент. Не добавляйте секрет в исходные файлы, конфигурацию, сохранённую в репозитории, снимки экрана и сообщения в поддержку.
Используйте личный ключ для работы от своего имени #
В настройках выбранной организации откройте вкладку Личные в разделе Ключи API, создайте личный ключ и задайте ему имя. Участник организации может создать такой ключ для себя. Права ключа зависят от текущего членства и действующих разрешений создателя. В отличие от сервисного ключа, личному нельзя назначить отдельную роль или ограничить его доступ отдельными движками локализации.
Такой ключ удобен для локального клиента, который действует от имени оператора. Если участник покинет организацию или потеряет права, доступ ключа тоже изменится. Используйте сервисный ключ, если автоматизация организации не должна зависеть от доступа конкретного человека.
Создайте сервисный ключ #
В настройках выбранной организации откройте вкладку Организация в разделе Ключи API и выберите Новый ключ организации. Сервисные ключи доступны на всех тарифных планах. Для создания требуется org:manage_api_keys.
Без RBAC ограничить доступ сервисного ключа нельзя: он позволяет читать данные и переводить с помощью любого движка локализации в организации. В форме создания вместо полей роли и движка показывается примечание.
Этот базовый доступ не позволяет ключу изменять или удалять движки локализации, проверять переводы или администрировать организацию.
С RBAC вы можете назначить ключу роль, ограничить доступ движками локализации или сделать и то и другое, а позже изменить эти настройки. У клиента должно быть право делегировать выбранную роль и переводить с помощью каждого движка локализации в заданной области доступа. Одного разрешения на чтение недостаточно, чтобы предоставить доступ к переводу.
Разрешённые сервисные роли: engine:read и engine:translate. Роль должна принадлежать организации и не может включать более широкие административные разрешения. Сервисный ключ может работать и без роли — только с явно предоставленными правами на ресурсы.
Настройте области доступа к движкам локализации и ресурсам контента по отдельности, затем считайте значение каждого сохранённого поля. Одно обновление прав может завершиться сбоем, а другое — успешно. Разрешения роли и явно предоставленные права складываются: узкая область доступа не отменяет более широкий доступ, полученный через роль. С RBAC само создание ключа не даёт ему прав, необходимых для перевода, если у него нет ни подходящей роли, ни прав на ресурсы.
Создавайте ключи и меняйте их область доступа через интерфейс управления ключами. Если вы автоматизируете этот процесс, проверьте, поддерживает ли выбранный клиент нужную операцию управления. Не рассчитывайте, что её поддерживают все клиенты.
Перед отключением RBAC
После отключения RBAC обычные сервисные ключи вернутся к доступу на чтение и перевод во всей организации. Сохранённые ограничения по ролям и движкам больше не будут ограничивать этот доступ. Если эти ограничения необходимы, отзовите или замените ключи до отключения RBAC. Для специализированных учётных данных, например ключей SCIM, действуют отдельные требования к доступу.
Замените или отзовите учётные данные #
Ротация — это замена ключа вручную:
- Создайте новый ключ нужного типа с минимально необходимыми правами.
- Сохраните его секрет в системе управления секретами клиента.
- Обновите настройки клиентов, использующих ключ, и проверьте выполнение небольшой целевой операции через поддерживаемый ими интерфейс.
- После проверки отзовите старый ключ. Если из-за утечки нужно немедленно ограничить доступ, сначала отзовите ключ и учтите перерыв в работе.
- Проверьте текущие записи ключей и ошибки клиентов, чтобы найти пропущенные зависимости.
Участник организации с доступом к записи ключа может отозвать обычный личный или сервисный ключ. Право на отзыв шире, чем право создавать сервисный ключ или менять его область доступа. Отозвать ключ SCIM может только владелец организации. При обсуждении удаления ключа указывайте его идентификатор, а не секрет.
Отзыв не удаляет копии ключа, сохранённые в других местах, и не завершает сеансы браузера. Этот процесс не подразумевает автоматической ротации или истечения срока действия по расписанию.
Настройте клиент, который будет использовать ключ #
REST-запросы используют заголовок X-API-Key выбранного API. Код 401 указывает на проблему с аутентификацией, а 403 — на отказ в доступе. В первом случае проверьте учётные данные, во втором — разрешения субъекта доступа и его область доступа к ресурсам. Не включайте учётные данные в URL, составленные вручную.
О том, как клиент передаёт и хранит учётные данные, читайте в разделах Аутентификация API, Аутентификация CLI или Контракт подключения MCP. Выбранный движок локализации должен оставаться в пределах прав этого клиента.