API-ключи аутентифицируют запросы к API локализации и MCP-серверу. В Lingo.dev есть два типа ключей — выберите тот, который подходит под ваш сценарий вызова API.
Два типа ключей#
| Персональный | Сервисный | |
|---|---|---|
| Владелец | Пользователь, который его создал | Нет — предназначен для автоматизации |
| Авторизация | Наследует роль RBAC создателя и доступ к движкам | Имеет собственную роль и/или доступ к отдельным движкам |
| Если владелец теряет доступ | Ключ тоже теряет доступ | Не затрагивается: всё определяется собственной ролью и областью доступа ключа |
| План | Любой тариф | Enterprise (требуется RBAC entitlement) |
| Типичное использование | Локальная разработка, MCP, разовые скрипты | CI/CD-пайплайны, продакшен-интеграции |
Персональные ключи используются по умолчанию. Сервисные ключи — это сущность на уровне организации, не привязанная к конкретному человеку. Они подходят для учётных данных, которые должны пережить смену ролей и уход сотрудников.
Создание ключа#
Откройте страницу API Keys в панели управления. Personal и Service находятся на отдельных вкладках — вкладка Service появляется только у организаций с тарифом Enterprise.
Нажмите Create API key, задайте имя (например, "Local MCP", "Staging key Макса") и скопируйте ключ из окна успешного создания. Ключ унаследует вашу текущую роль RBAC и доступ к отдельным движкам.
Видимость ключа
Полный API-ключ показывается только один раз — в момент создания. Скопируйте его и сохраните в надёжном месте: после закрытия окна получить его повторно уже не получится.
Сервисные ключи и RBAC#
Сервисные ключи повторяют пользовательскую модель: у пользователя может быть роль уровня организации (общие разрешения через Roles & Permissions) И/ИЛИ доступ к отдельным движкам за счёт добавления в конкретные движки. Сервисный ключ работает по тому же принципу:
- Только роль — разрешения роли действуют на всю организацию. Если она включает
engine:access, ключ получает доступ ко всем движкам в организации. - Без роли + доступ к движкам — ключ будет ограничен движками, которые вы отметите при создании. Позже список можно изменить через кнопку Engines x/y рядом с ключом.
- Роль + доступ к движкам — оба источника прав складываются. Если роль даёт
engine:access, приоритет остаётся за её общими правами; иначе используется список выбранных движков. - Ни того ни другого — ключ проходит аутентификацию, но не может обратиться ни к одному движку. Это удобно как временная заготовка, пока вы настраиваете область доступа, но в продакшене такой ключ бесполезен.
Защита от эскалации прав действует и при создании, и при редактировании:
- Выбранная роль должна принадлежать той же организации.
- Набор разрешений роли должен быть подмножеством
engine:access— более широкие роли (например, включающиеorg:manage_team) отклоняются. - Вы можете добавить движок в область доступа ключа, только если у вас уже есть доступ к этому движку.
Если тариф Enterprise перестанет действовать
Сервисные ключи входят в RBAC entitlement. Если entitlement будет отключён, все сервисные ключи в организации будут деактивированы — запросы начнут возвращать 403 и сообщение со ссылкой на тариф, а не на область доступа к движкам. Персональные ключи это не затронет. Либо восстановите тариф Enterprise, либо перейдите на персональный API-ключ.
Использование ключа#
Передавайте API-ключ в заголовке X-API-Key при каждом запросе — формат одинаков для обоих типов ключей:
curl -X POST https://api.lingo.dev/process/localize \
-H "X-API-Key: your_api_key" \
-H "Content-Type: application/json" \
-d '{"engineId": "eng_abc123", "sourceLocale": "en", "targetLocale": "de", "data": {"greeting": "Hello"}}'Один и тот же ключ подходит и для API локализации, и для MCP-сервера.
Безопасность#
- Ключи хранятся в виде хешей — Lingo.dev не может восстановить ключ после создания. Для ротации удалите его и создайте заново.
- Персональные ключи в реальном времени следуют разрешениям своего создателя. Если роль создателя понижается или доступ к движку отзывается, ключ потеряет тот же доступ при следующем запросе.
- Персональный ключ, создатель которого был удалён из организации, продолжает работать только пока RBAC отключён (устаревшее поведение). Как только RBAC включается, доступ будет запрещён — замените ключ до того, как он станет «осиротевшим».
- Сервисные ключи имеют собственные права доступа. Изменения роли или области доступа на вкладке Service вступают в силу сразу; удаление ключа отзывает доступ.
- Количество ключей на организацию не ограничено.
