API 키는 로컬라이제이션 API와 MCP 서버로 보내는 요청을 인증합니다. Lingo.dev는 두 가지 유형의 키를 지원하므로, API를 호출하는 주체에 맞는 키를 선택하면 됩니다.
두 가지 키 유형#
| 개인용 | 서비스 | |
|---|---|---|
| 소유자 | 키를 만든 사용자 | 없음 — 자동화용 |
| 권한 | 생성자의 RBAC 역할과 엔진 권한을 상속 | 자체 역할 및/또는 엔진별 범위를 가짐 |
| 소유자가 접근 권한을 잃는 경우 | 키도 함께 접근 권한을 잃음 | 영향 없음 — 키 자체의 역할/범위로 제어됨 |
| 플랜 | 모든 플랜 | Enterprise(RBAC 권한 필요) |
| 주요 사용 사례 | 로컬 개발, MCP, 임시 스크립트 | CI/CD 파이프라인, 프로덕션 연동 |
개인용 키가 기본값입니다. 서비스 키는 특정 개인과 분리된 조직 단위 리소스이므로, 직원 퇴사 이후에도 유지되어야 하고 역할 변경에도 영향받지 않아야 하는 자격 증명에 적합합니다.
키 생성하기#
대시보드에서 API 키 페이지를 여세요. 개인용과 서비스용은 각각 별도 탭으로 제공되며, 서비스 탭은 조직이 Enterprise 플랜일 때만 표시됩니다.
Create API key를 클릭하고 이름(예: "Local MCP", "Max's staging key")을 입력한 다음, 성공 대화상자에서 키를 복사하세요. 이 키는 현재 내 RBAC 역할과 엔진별 권한을 그대로 상속합니다.
키 표시 방식
전체 API 키는 생성 시 한 번만 표시됩니다. 반드시 복사해 안전하게 보관하세요 — 대화상자를 닫으면 다시 확인할 수 없습니다.
서비스 키와 RBAC#
서비스 키는 사용자 모델과 같은 방식으로 동작합니다. 사용자는 조직 수준 역할(Roles & Permissions을 통한 포괄 권한)과/또는 특정 엔진에 추가되면서 부여되는 엔진별 권한을 가질 수 있습니다. 서비스 키도 마찬가지입니다.
- 역할만 있음 — 역할의 권한이 조직 전체에 적용됩니다. 여기에
engine:access이 포함되면, 이 키는 조직의 모든 엔진에 접근할 수 있습니다. - 역할 없음 + 엔진 범위 — 키는 생성 시 선택한 엔진으로만 제한됩니다. 이후에는 키 옆의 Engines x/y 버튼에서 목록을 업데이트할 수 있습니다.
- 역할 + 엔진 범위 — 두 권한은 누적됩니다. 역할이
engine:access을 부여하면 그 포괄 권한이 우선하고, 그렇지 않으면 엔진별 목록이 적용됩니다. - 둘 다 없음 — 키는 인증은 되지만 어떤 엔진에도 접근할 수 없습니다. 범위를 연결하는 동안 임시 자리표시자로는 유용할 수 있지만, 프로덕션에서는 의미가 없습니다.
권한 상승 방지 장치는 생성 시와 수정 시 모두 적용됩니다.
- 선택한 역할은 같은 조직에 속해 있어야 합니다.
- 역할의 권한 집합은
engine:access의 부분 집합이어야 합니다 — 더 넓은 권한을 가진 역할(예:org:manage_team이 포함된 역할)은 거부됩니다. - 키 범위에 엔진을 추가하려면, 본인에게 이미 해당 엔진 접근 권한이 있어야 합니다.
Enterprise 플랜이 만료되면
서비스 키는 RBAC 권한에 포함됩니다. 이 권한이 제거되면 조직의 모든 서비스 키가 비활성화됩니다 — 요청은 403을 반환하며, 메시지는 엔진 범위가 아니라 플랜 문제를 가리킵니다. 개인용 키는 영향받지 않습니다. Enterprise 플랜을 복구하거나 개인용 API 키로 교체하세요.
키 사용하기#
모든 요청의 X-API-Key 헤더에 API 키를 전달하세요 — 전송 형식은 두 유형 모두 동일합니다.
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가 켜지는 순간 거부되므로, 고아 상태가 되기 전에 교체하세요.
- 서비스 키는 자체 권한을 가집니다. 서비스 탭에서 역할이나 범위를 수정하면 즉시 반영되며, 키를 삭제하면 권한도 함께 취소됩니다.
- 조직당 키 개수 제한은 없습니다.
