API 키
개인 권한과 서비스 권한 중에서 선택하고, 한 번만 표시되는 비밀 값을 안전하게 저장하세요. 호출 주체를 파악하면서 자격 증명을 교체하세요.
API 키를 사용하면 호출 주체가 지정된 권한으로 작업할 수 있습니다. 개인 키는 해당 사용자의 조직 소속 상태와 권한을 따릅니다. 조직 서비스 키는 조직에 속하므로 특정 동료가 퇴사해도 자동화를 독립적으로 유지할 수 있습니다. 역할 기반 접근 제어(RBAC)를 사용하면 서비스 키에 별도의 역할과 리소스 범위를 지정할 수도 있습니다.
비밀 값은 생성할 때만 표시되며, 이후에는 키 기록에서 복구할 수 없습니다. 비밀 관리 도구나 호출 주체가 지원하는 자격 증명 저장소에 즉시 저장하세요. 소스 파일, 커밋된 설정, 스크린샷, 지원 문의 메시지에는 포함하지 마세요.
개인 자격으로 수행하는 작업에 개인 키 사용하기 #
선택한 조직의 설정 → API 키 → 개인에서 개인 키를 만들고 이름을 지정하세요. 구성원은 본인이 사용할 키를 만들 수 있습니다. 이 키의 권한은 생성자의 현재 조직 소속 상태와 실제로 적용되는 권한을 따릅니다. 서비스 키와 달리 별도의 역할이나 로컬라이제이션 엔진별 범위를 부여할 수는 없습니다.
개인 키는 운영자 본인의 권한으로 동작하는 로컬 호출 주체에 유용합니다. 구성원이 조직을 떠나거나 권한을 잃으면 키의 접근 권한도 바뀝니다. 조직의 자동화가 특정 개인의 접근 권한 유지 여부에 의존하지 않아야 한다면 서비스 키를 사용하세요.
서비스 키 만들기 #
선택한 조직의 설정 → API 키 → 조직에서 새 조직 키를 선택하세요. 서비스 키는 모든 요금제에서 사용할 수 있습니다. 생성하려면 org:manage_api_keys 권한이 필요합니다.
RBAC를 사용하지 않으면 서비스 키의 범위를 제한할 수 없습니다. 이 키는 조직의 모든 로컬라이제이션 엔진에서 읽기와 번역을 수행할 수 있습니다. 생성 양식에는 역할 및 엔진 필드 대신 안내문이 표시됩니다.
이 기본 접근 권한으로는 로컬라이제이션 엔진 수정·삭제, 번역 검토, 조직 관리를 할 수 없습니다.
RBAC를 사용하면 키에 역할과 로컬라이제이션 엔진 범위 중 하나 또는 둘 다를 지정하고 나중에 수정할 수 있습니다. 호출 주체는 선택한 역할을 위임할 수 있어야 하며, 지정된 범위에 속한 모든 로컬라이제이션 엔진에서 번역할 수 있어야 합니다. 읽기 권한만으로는 번역 범위를 부여할 수 없습니다.
서비스 역할로 허용되는 항목은 engine:read 및 engine:translate입니다. 역할은 해당 조직에 속해야 하며, 더 광범위한 관리 권한을 포함해서는 안 됩니다. 서비스 키에 역할을 지정하지 않고 명시적으로 부여한 리소스 권한만 사용하도록 할 수도 있습니다.
로컬라이제이션 엔진 범위와 콘텐츠 리소스 범위를 별도로 설정한 다음, 저장된 각 필드의 값을 다시 조회하세요. 한 권한 업데이트가 성공해도 다른 업데이트는 실패할 수 있습니다. 역할 권한과 명시적으로 부여한 권한은 합산됩니다. 범위를 좁게 지정해도 역할에 따른 더 넓은 접근 권한이 취소되지는 않습니다. RBAC를 사용할 때 적절한 역할도 리소스 권한도 없는 키는 생성하는 것만으로 실제 번역에 필요한 권한을 얻지 못합니다.
키 생성과 범위 수정에는 키 관리 인터페이스를 사용하세요. 이 관리 과정을 자동화할 때는 모든 클라이언트가 필요한 관리 작업을 지원한다고 가정하지 말고, 선택한 클라이언트가 해당 작업을 제공하는지 확인하세요.
RBAC를 제거하기 전에
RBAC를 제거하면 일반 서비스 키는 조직 전체에 대한 읽기 및 번역 권한으로 돌아갑니다. 저장된 역할 및 엔진 제한은 더 이상 해당 접근을 제한하지 않습니다. 이러한 제한이 필요하다면 RBAC를 제거하기 전에 키를 폐기하거나 교체하세요. SCIM 키처럼 특정 용도로 사용하는 자격 증명에는 별도의 접근 요건이 적용됩니다.
자격 증명 교체 또는 폐기하기 #
키 교체는 다음과 같이 수동으로 진행합니다.
- 사용하려는 키 유형과 필요한 최소 권한으로 대체 키를 만드세요.
- 호출 주체의 비밀 관리 수단에 비밀 값을 저장하세요.
- 이 키에 의존하는 호출 주체를 업데이트하고, 각 호출 주체가 지원하는 인터페이스에서 의도한 소규모 작업이 정상적으로 수행되는지 확인하세요.
- 확인이 끝나면 기존 키를 폐기하세요. 키 노출로 즉시 차단해야 한다면 먼저 폐기하고 그에 따른 중단에 대비하세요.
- 현재 키 기록과 호출 주체의 실패 내역을 살펴 누락된 의존 관계가 있는지 확인하세요.
키 기록에 접근할 수 있는 조직 구성원은 일반 개인 키나 서비스 키를 폐기할 수 있습니다. 이 폐기 권한은 서비스 키를 생성하거나 범위를 수정하는 권한보다 더 폭넓게 허용됩니다. SCIM 키를 폐기하려면 조직 소유자여야 합니다. 키 폐기를 논의할 때는 비밀 값이 아닌 키 식별자를 사용하세요.
키를 폐기해도 다른 곳에 저장된 복사본이 지워지거나 브라우저 세션이 해제되지는 않습니다. 이 관리 과정이 자동 교체나 만료 일정까지 의미하는 것은 아닙니다.
실제 호출 주체 설정하기 #
REST 요청은 선택한 API의 X-API-Key 헤더를 사용합니다. 401은 인증 문제를, 403은 권한 거부를 나타냅니다. 401이면 자격 증명을, 403이면 인증 주체의 권한과 리소스 범위를 확인하세요. 임의로 구성한 URL에 자격 증명을 넣지 마세요.
호출 주체의 통신 및 저장 방식은 API 인증, CLI 인증 또는 MCP 연결 규약을 참고하세요. 선택한 로컬라이제이션 엔진은 해당 호출 주체의 권한 범위 안에 있어야 합니다.