API-ключи
API-ключи аутентифицируют запросы к API локализации и MCP-серверу. В Lingo.dev есть два типа ключей — выберите тот, который подходит под ваш сценарий вызова API.
Два типа ключей#
| Персональный | Организационный | |
|---|---|---|
| Владелец | Пользователь, который его создал | Нет — предназначен для автоматизации |
| Авторизация | Наследует роль RBAC создателя и доступ к движкам | Имеет собственную роль и/или доступ к отдельным движкам |
| Если владелец теряет доступ | Ключ тоже теряет доступ | Не затрагивается: всё определяется собственной ролью и областью доступа ключа |
| План | Любой тариф | Enterprise (требуется RBAC entitlement) |
| Типичное использование | Локальная разработка, MCP, разовые скрипты | CI/CD-пайплайны, продакшен-интеграции |
Персональные ключи — вариант по умолчанию. Организационные ключи — это сущность уровня организации, не привязанная ни к какому конкретному человеку. Именно такой формат подходит для учётных данных, которые должны пережить смену сотрудников и изменения ролей.
Создание ключа#
Откройте страницу API-ключи в разделе Настройки. Персональные и организационные ключи находятся на разных вкладках; вкладка «Организационные» доступна только в плане Enterprise.
Нажмите Новый персональный ключ, задайте имя (например, «Local MCP» или «Staging-ключ Макса») и скопируйте ключ, когда он появится на экране. Ключ наследует вашу текущую роль RBAC и права доступа к конкретным движкам.
Видимость ключа
Полный API-ключ показывается только один раз — в момент создания. Скопируйте его и сохраните в надёжном месте: после закрытия окна получить его повторно уже не получится.
Организационные ключи и RBAC#
Организационные ключи работают по той же модели, что и пользователи: у пользователя может быть роль на уровне организации (общие разрешения через Roles & Permissions) и/или права доступа к отдельным движкам. Организационный ключ устроен так же:
- Только роль — разрешения роли действуют на всю организацию. Если она включает
engine:access, ключ получает доступ ко всем движкам в организации. - Без роли + область движков — ключ ограничен теми движками, которые вы выбрали при создании. Список движков можно обновить позже, отредактировав ключ.
- Роль + доступ к движкам — оба источника прав складываются. Если роль даёт
engine:access, приоритет остаётся за её общими правами; иначе используется список выбранных движков. - Ни того ни другого — ключ проходит аутентификацию, но не может обратиться ни к одному движку. Это удобно как временная заготовка, пока вы настраиваете область доступа, но в продакшене такой ключ бесполезен.
Защита от эскалации прав действует и при создании, и при редактировании:
- Выбранная роль должна принадлежать той же организации.
- Набор разрешений роли должен быть подмножеством
engine:access— более широкие роли (например, включающиеorg:manage_team) отклоняются. - Вы можете добавить движок в область доступа ключа, только если у вас уже есть доступ к этому движку.
Если тариф Enterprise перестанет действовать
Организационные ключи входят в набор прав RBAC. Если права отзываются, все организационные ключи деактивируются — запросы возвращают код 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 включается, доступ будет запрещён — замените ключ до того, как он станет «осиротевшим».
- Организационные ключи имеют собственные права. Изменение роли или области действия вступает в силу сразу; удаление ключа отзывает его.
- Количество ключей на организацию не ограничено.