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