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는 생략해도 됩니다.
이 범위는 편리한 만큼 신중히 봐야 할 부분이기도 합니다. 키가 유출되면 조직이 접근할 수 있는 모든 대상에 그대로 접근할 수 있기 때문입니다. 따라서 다른 프로덕션 시크릿과 동일하게 다루세요. 환경 변수나 시크릿 매니저에서 불러오고, 절대 커밋하지 말고, 반드시 서버 측에만 보관해야 합니다. 이 키는 누구나 들여다볼 수 있는 브라우저가 아니라 백엔드에서 발생하는 호출을 인증하기 위한 것입니다. 같은 원칙은 실시간 WebSocket에도 적용됩니다. 동일한 키로 인증하므로 연결 역시 서버 측에서 열어야 합니다.
키 생성과 관리는 대시보드의 API Keys 섹션에서 할 수 있습니다.
한 번 저장하지 않으면 끝입니다#
키는 생성되는 순간 단 한 번만 표시됩니다. 해당 대화상자를 닫으면 다시 조회할 수 없습니다.
페이지를 떠나기 전에 키를 복사하세요
API 키는 생성 시 한 번만 표시됩니다. 키가 나타나는 즉시 시크릿 매니저나 환경 변수에 저장하세요. 이후에는 복구할 수 없습니다. 키를 분실했거나 유출이 의심된다면 API Keys 대시보드에서 새 키를 생성하세요.
여기서는 가장 쉬운 방법이 가장 안전한 방법이기도 합니다. 생성 직후 키를 제대로 저장해 두는 것이 가장 빠른 길이자, 나중에 누구도 다시 확인할 수 없는 자격 증명 때문에 프로덕션 연동이 막히는 일을 막는 유일한 방법입니다.
다음 단계#
이제 어떤 호출이든 인증할 수 있습니다. 다음으로 함께 보면 좋은 것은 두 가지입니다. 요청이 거부됐을 때 어떤 응답이 돌아오는지 확인하는 것, 그리고 이 헤더로 사용할 수 있는 엔드포인트를 살펴보는 것입니다.
