Аутентификация API

Аутентифицируйте запросы к API и предоставляйте нужный доступ для каждой операции.

Передавайте ключ API Lingo.dev в заголовке X-API-Key. Используйте https://api.lingo.dev/v2 как базовый URL для справочников API в этом разделе.

http
GET /v2/organizations/YOUR_ORGANIZATION_ID/localization/jobs HTTP/1.1
Host: api.lingo.dev
X-API-Key: YOUR_API_KEY

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

Выберите учётные данные #

Личный ключ действует с учётом текущего членства пользователя в организации и прав пользователя. Сервисный ключ принадлежит организации и подходит для сервиса, который работает без участия человека. Доступ по нему определяется правами роли и правами на ресурсы. Явно заданное более узкое право не ограничивает доступ, уже предоставленный ролью.

API также принимает токен доступа сеанса пользователя, вошедшего в систему, в качестве Authorization: Bearer <access-token>. Специалисты по проверке могут отправлять решения, используя свой сеанс или личный ключ. Сервисные ключи не позволяют принимать решения в рамках ручной проверки, так как эти действия должны быть связаны с конкретным человеком.

Используйте только один способ аутентификации в каждом запросе. Регистр символов в названиях заголовков не имеет значения.

Выберите организацию и движок #

Маршруты, привязанные к организации, содержат orgId в пути. Чтобы найти ИД организаций для пользователя или личного ключа, см. GET /v2/users/me/memberships. Для сервисного ключа используйте организацию, которой он принадлежит. ИД движка указывает на движок, настроенный в Studio. Чтобы получить список доступных движков, используйте GET /v2/organizations/:orgId/engines.

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

Передача ИД организации или движка не даёт доступа. Если ресурс находится вне области доступа того, кто отправляет запрос, API может вернуть 404. Поэтому, если известный ресурс не найден, проверьте и его ИД, и права того, кто отправляет запрос.

Выясните причину ошибки доступа #

Проверьте не только HTTP-статус, но и ответ с описанием проблемы. 401 означает, что учётные данные отсутствуют, недействительны или срок их действия истёк. 402 указывает на проблему с оплатой или условие тарифного плана, в том числе на отключение сервисного ключа после перехода на более низкий уровень RBAC. 403 означает отказ в доступе или необходимость идентифицировать пользователя. Проблемы с конфигурацией движка и лимитами учётной записи нужно устранять отдельно.

Для диагностики сохраните значение type из описания проблемы, статус и ИД ресурсов, которые не являются секретными. Никогда не записывайте заголовок аутентификации в логи.

Замените ключ #

Создайте новый ключ, предоставьте нужный доступ и обновите секрет сервиса. Прежде чем отозвать старый ключ, убедитесь, что с новым ключом удаётся получить существующее задание и скачать результат. Сохраните записанные ИД заданий: замена учётных данных не меняет эти идентификаторы.