API 키

개요

API 키는 ElevenLabs API 요청을 인증하고 워크스페이스 할당량에 대한 사용량을 추적합니다. 두 가지 유형이 있습니다.

• 사용자 API 키는 개별 사용자에게 속하며 해당 사용자의 워크스페이스 리소스 접근 권한을 상속합니다. 개인 개발 및 스크립트에 적합하며, 만료일을 설정해 일정 기간 후 자동으로 작동을 중지하게 할 수 있습니다. 개인과 연결되어 있으므로 해당 사용자의 접근 권한이 변경되거나 워크스페이스를 떠나면 사용자 API 키에도 영향을 미칩니다. 개인 API 키를 생성하려면 풀 시트가 필요합니다.
• 서비스 계정 API 키는 개인이 아닌 서비스 계정에 속하므로, 개별 멤버십이 변경되어도 계속 작동합니다. 백엔드 시스템, 자동화 및 프로덕션 워크로드에 권장됩니다. 서비스 계정은 여러 시트를 사용하는 고객에게 제공되며 워크스페이스 관리자가 관리합니다.

API 키는 비밀 정보입니다. 다른 사람과 공유하거나 클라이언트 측 코드(브라우저, 앱)에 노출하지 마세요. 요청에 키를 포함하는 방법은 API 인증 레퍼런스를 참조하세요.

두 유형의 키 모두 여러 방식으로 제한할 수 있습니다.

1. 범위 제한: 키가 접근할 수 있는 API 엔드포인트를 제한합니다.
2. 크레딧 할당량: 사용량을 제어할 맞춤 크레딧 한도를 설정합니다.
3. IP 허용 목록: 키를 특정 IP 주소 또는 CIDR 범위로 제한합니다. IP 허용 목록을 참조하세요.

만료되는 사용자 API 키

사용자 API 키에는 만료일을 설정하여 일정 기간 후 자동으로 작동을 중지하게 할 수 있습니다. 이렇게 하면 유출되거나 잊힌 키를 사용할 수 있는 기간을 제한하며, 개인에게 연결된 키의 단기적인 특성에 적합합니다.

개인 API 키 설정에서 키를 생성하거나 편집할 때 만료일을 설정하세요. Expire After 선택기에서 15분부터 30일까지의 사전 설정을 선택하거나, Never(기본값)로 유지하세요. Expires 열에서 각 키의 만료 시점을 확인할 수 있습니다.

키가 만료되면 인증이 중지되고 해당 키로 보낸 요청은 401 오류와 함께 거부됩니다. 키가 만료되기 전에 편집하여 만료일을 연장하거나 해제할 수 있으며, 그렇지 않으면 새 키로 교체하세요.

API 키 교체

두 경우 모두 교체 절차는 같습니다. 새 키를 만들고, 애플리케이션을 새 키로 전환한 다음, 기존 키를 삭제하세요.

사용자 API 키는 대시보드에서 교체합니다. 개인 API 키 설정을 열고 새 키를 만든 후 전환이 완료되면 기존 키를 삭제하세요.

서비스 계정 API 키는 대시보드 또는 API를 통해 교체할 수 있습니다.

• 대시보드에서 오른쪽 상단의 프로필 아이콘을 클릭하고 Workspace settings를 선택한 다음 Service Accounts 탭을 엽니다. 동일한 서비스 계정에 대해 새 키를 만들고, 전환이 완료되면 기존 키를 삭제하세요.
• API를 통해 동일한 서비스 계정에 대한 새 키를 생성한 다음, 기존 키를 삭제하세요.

IP 허용 목록

API 키가 특정 IP 주소 또는 CIDR 범위에서만 작동하도록 제한할 수 있습니다. 다른 IP에서 보낸 요청은 403 오류와 함께 거부됩니다.

지원 형식

• 개별 IPv4 주소(예: 203.0.113.10)
• 개별 IPv6 주소(예: 2001:db8::1)
• CIDR 범위(예: 203.0.113.0/24)

API 키당 1개에서 100개까지 항목을 추가할 수 있습니다. 단일 IP 주소는 자동으로 /32(IPv4) 또는 /128(IPv6)로 정규화됩니다.

유출된 키 감지

ElevenLabs는 GitHub의 시크릿 스캐닝 파트너 프로그램에 참여하고 있습니다. ElevenLabs API 키가 공개 GitHub 리포지토리에 커밋되면 GitHub가 ElevenLabs에 알리고 무단 사용을 방지하기 위해 해당 키가 자동으로 비활성화됩니다.

이 방식으로 비활성화된 키의 disable_reason은 exposed_publicly로 표시됩니다. 접근 권한을 복구하려면 키를 교체하고 애플리케이션이 새 키를 사용하도록 업데이트하세요.

키 직접 비활성화

키가 유출되었다고 판단되면 키 보유자가 API 키 비활성화 엔드포인트를 사용해 직접 비활성화할 수 있습니다. 쿼리 매개변수 api_key_name=self와 함께 호출하세요. 이는 요청 인증에 사용된 키를 비활성화할 의도가 있음을 명시적으로 확인하기 위해 필요합니다.

키를 비활성화할 수 있는 사용자 제어

third_party_disable_allowed 설정은 키 보유자가 직접 비활성화 엔드포인트를 통해 또는 키가 공개적으로 유출되었을 때 자동으로 키를 비활성화할 수 있는지를 제어합니다. 기본적으로 엔터프라이즈 이외의 플랜에서는 활성화되고 엔터프라이즈 플랜에서는 비활성화됩니다.

키별: 서비스 계정 API 키를 생성하거나 업데이트할 때 third_party_disable_allowed를 설정하세요. 워크스페이스 기본값을 사용하려면 생략하고, 개별 키를 워크스페이스 기본값으로 재설정하려면 업데이트 시 clear를 전달하세요.

워크스페이스 전체: 워크스페이스 관리자는 워크스페이스 타사 비활성화 정책 설정 엔드포인트를 사용하여 모든 키의 설정을 한 번에 재정의할 수 있습니다.

• true이면 워크스페이스의 모든 키를 보유자가 비활성화할 수 있습니다.
• false이면 모든 키에서 이를 금지합니다.
• null이면 워크스페이스 전체 재정의가 제거되고 각 키의 자체 값과 플랜 기본값이 다시 적용됩니다.