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

Каждый запрос к API должен подтверждать, кто именно его отправляет и к каким движкам организации у него есть доступ. В Lingo.dev для этого в каждый запрос добавляется один заголовок: X-API-Key. Никакого обмена токенами, сессий или OAuth-цепочки, которую пришлось бы отдельно обвязывать в скриптах, — один и тот же заголовок вы добавляете и к синхронному вызову localize, и к отправке асинхронной задачи.

У этой простоты есть важная особенность, о которой лучше знать до первого запроса: ключ привязан к организации и показывается только один раз. На этой странице разберём, как выглядит этот заголовок, к чему даёт доступ ключ и где его хранить. О том, что API возвращает при неверном заголовке, см. страницу Ошибки и коды состояния.

Только начинаете работать с API?

Начните с раздела Обзор, чтобы разобраться с базовым URL и моделью движка. Эта страница исходит из того, что API-ключ у вас уже есть и вам нужно только передать его в запросе.

Заголовок#

Передавайте ключ в заголовке X-API-Key в каждом запросе:

bash

X-API-Key: your_api_key

В полном виде это выглядит так: один и тот же заголовок используется для всех эндпоинтов, синхронных и асинхронных:

bash

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 возвращает, когда отклоняет запрос, и посмотреть, какие эндпоинты открывает этот заголовок.

Ошибки и коды состояния

Что означают 401, 403 и другие коды — и как с ними работать

API Keys

Создание, именование и управление ключами вашей организации

Обзор

Базовый URL, модель движка и два режима API