Каждый запрос к API должен подтверждать, кто именно его отправляет и к каким движкам организации у него есть доступ. В Lingo.dev для этого в каждый запрос добавляется один заголовок: X-API-Key. Никакого обмена токенами, сессий или OAuth-цепочки, которую пришлось бы отдельно обвязывать в скриптах, — один и тот же заголовок вы добавляете и к синхронному вызову localize, и к отправке асинхронной задачи.
У этой простоты есть важная особенность, о которой лучше знать до первого запроса: ключ привязан к организации и показывается только один раз. На этой странице разберём, как выглядит этот заголовок, к чему даёт доступ ключ и где его хранить. О том, что API возвращает при неверном заголовке, см. страницу Ошибки и коды состояния.
Только начинаете работать с API?
Начните с раздела Обзор, чтобы разобраться с базовым URL и моделью движка. Эта страница исходит из того, что API-ключ у вас уже есть и вам нужно только передать его в запросе.
Заголовок#
Передавайте ключ в заголовке X-API-Key в каждом запросе:
X-API-Key: your_api_keyВ полном виде это выглядит так: один и тот же заголовок используется для всех эндпоинтов, синхронных и асинхронных:
curl https://api.lingo.dev/jobs/localization \
-H "X-API-Key: your_api_key" \
-H "Content-Type: application/json" \
-d '{
"sourceLocale": "en",
"targetLocales": ["de", "ja"],
"data": { "greeting": "Welcome aboard" }
}'Если ключ указан корректно, эндпоинт возвращает обычный ответ — в этом случае 202 с groupId. Если заголовок отсутствует или недействителен, вернётся 401. Этот ответ и остальные коды описаны на странице Ошибки.
К чему даёт доступ один ключ#
Ключ принадлежит организации, а не отдельному движку. Один ключ даёт доступ ко всем движкам локализации в этой организации, поэтому не нужно выпускать отдельные учётные данные для каждого движка — один и тот же X-API-Key работает и для маркетингового движка, и для движка документации, а engineId можно не указывать, чтобы обратиться к движку организации по умолчанию.
Это удобно, но именно этот момент стоит учитывать в первую очередь: если ключ утечёт, он откроет доступ ко всему, к чему есть доступ у организации. Поэтому обращайтесь с ним как с любым production-секретом. Подгружайте его из переменной окружения или менеджера секретов, никогда не коммитьте в репозиторий и храните только на стороне сервера — ключ предназначен для аутентификации вызовов с вашего бэкенда, а не из браузера, где его может прочитать кто угодно. То же правило действует и для realtime-поверхности WebSocket: она использует тот же ключ, поэтому такие соединения тоже нужно открывать на стороне сервера.
Создавать ключи и управлять ими можно в разделе API Keys в панели управления.
Сохраняется один раз — или теряется навсегда#
Ключ показывается только один раз — в момент создания. После закрытия этого диалога получить его повторно уже нельзя.
Скопируйте ключ, прежде чем уйти со страницы
API-ключи показываются только один раз при создании. Сразу сохраните ключ в менеджере секретов или в переменной окружения, как только он появится, — позже восстановить его будет нельзя. Если ключ потерян или есть подозрение, что он утёк, создайте новый в разделе API Keys панели управления.
Это редкий случай, когда самый простой и самый безопасный путь совпадают: сохранить ключ сразу при создании — и быстрее всего, и единственный способ не застопорить production-интеграцию из-за учётных данных, которые потом никто не сможет посмотреть повторно.
Что дальше#
Теперь вы можете аутентифицировать любой запрос. Дальше логично сделать две вещи: разобраться, что API возвращает, когда отклоняет запрос, и посмотреть, какие эндпоинты открывает этот заголовок.
