Skip to main content
API 키는 외부 코드가 워크스페이스를 대신해 vox.ai를 쓸 때 내는 값이에요. 서버에서 REST API를 부르는 서버용 키와 브라우저나 모바일 앱에서 세션을 시작하는 클라이언트용 키, 두 가지가 있어요. 설정의 API 키 목록. 이름, 종류, API 키, 생성일시, 마지막 사용이 보여요

API 키 종류 고르기

키를 쓸 곳에 맞춰 용도를 하나 고르세요. 용도는 만든 뒤 바꿀 수 없어요.

API 키 만들기

1

만들기 창 열기

설정 > API 키에서 API 키 만들기를 누르세요. 키를 만들고 삭제하는 일은 오너와 관리자가 해요.
2

이름과 용도 정하기

API 키 이름에 키를 구분할 이름을 64자 안으로 적고, 용도에서 서버용이나 클라이언트용을 고르세요. 서버용이면 허용 IP (선택), 클라이언트용이면 허용 도메인 (선택) 항목도 정할 수 있어요. 설정은 웹페이지와 모바일 앱 연결하기에 있어요.
3

키 복사해 보관하기

만들기를 누르면 키가 나와요. API 키 복사를 눌러 서버용 키는 서버의 환경 변수 VOX_API_KEY에 저장하세요. 서버용 키는 이 창을 닫으면 다시 볼 수 없어요.
4

목록에서 확인하기

목록의 종류, API 키, 마지막 사용으로 키를 구분하세요. 서버용 키는 끝 4자리만 보이고, 클라이언트용 키는 가운데를 줄여서 보여 줘요.
API 키를 만든 직후 키가 한 번만 보이는 창

서버용 키를 쓸 IP 정하기

서버용 키에 허용 IP를 정하면 그 밖의 주소에서 온 요청은 API_KEY_IP_NOT_ALLOWED(403)로 거절돼요. 키를 만들 때 허용 IP (선택) 칸에 넣거나, 목록에서 키 행의 ⋮ 메뉴 수정으로 고치세요. IP 주소나 범위(10.0.0.0/24)를 20개까지 넣을 수 있고, 비우면 제한이 없어요.

웹페이지와 모바일 앱 연결하기

브라우저와 모바일 앱의 음성 SDK에는 클라이언트용 키를 넣으세요. 용도에서 클라이언트용을 골라 키를 만들고, 목록에서 pk_ 키를 복사해 SDK의 apiKey에 넣으세요. 사용법은 JavaScript와 React에 있어요.
  • 허용 도메인 (선택): 키를 쓸 사이트를 example.com처럼 20개까지, 한 항목은 253자까지 넣을 수 있어요. 넣으면 그 사이트와 하위 도메인에서만 세션이 시작돼요. 비우면 어디서나 쓸 수 있어요. 모바일 앱은 도메인 정보를 보내지 않으니 앱 전용 키는 비워 두세요.
  • 세션 범위: 클라이언트용 키는 에이전트를 가리지 않아요. 키가 속한 워크스페이스와 그 직속 하위 워크스페이스의 어느 에이전트와 버전으로든 세션을 시작할 수 있으니, 허용 도메인으로 쓸 수 있는 사이트를 좁혀 두세요. 하위 워크스페이스마다 앱을 따로 배포한다면 하위 워크스페이스의 키를 쓰세요.
  • 시작 한도: 키와 IP마다 분당 30회까지 세션을 시작할 수 있어요.
  • 서버용 키: 클라이언트용 키가 나온 뒤에 만든 서버용 키는 브라우저와 모바일 앱에서 세션을 시작할 수 없어요. 그 전에 만든 서버용 키는 그대로 동작해요. 브라우저나 모바일 앱에 넣어 쓰던 서버용 키는 클라이언트용 키를 새로 만들어 바꾸고, 이전 키는 행 메뉴의 삭제로 지우세요.
pk_로 보낸 external_id는 브라우저가 주장한 값이에요. 고객 메모리를 쓰는 에이전트에는 pk_와 external_id를 함께 쓰지 마세요.

API로 클라이언트용 키 관리하기

하위 워크스페이스가 많아 대시보드에서 일일이 만들기 어렵다면 API로 클라이언트용 키(pk_)를 만들고, 목록을 보고, 폐기할 수 있어요. 요청 경로는 세 가지 모두 /v3/organizations/{organization_id}/api-keys이고, 키 종류는 type으로 정해요. 아래 예제의 $VOX_API_KEY는 호출에 쓰는 서버용 키, $ORGANIZATION_ID는 키를 만들 워크스페이스의 ID예요.
  • type: secret(서버용)이나 publishable(클라이언트용)이에요. 생략하면 secret이라서, 클라이언트용 키를 다룰 때는 type을 꼭 적으세요. 목록 조회만 all로 두 종류를 함께 볼 수 있어요.
  • 한도: API로는 종류마다 워크스페이스당 20개까지 만들 수 있어요. 대시보드에서 만든 키도 이 개수에 들어가요.

상위 키와 하위 키 고르기

호출하는 키가 어느 워크스페이스의 것이냐에 따라 만들 수 있는 키가 달라요.
  • 상위 워크스페이스의 클라이언트용 키: 직속 하위 워크스페이스 모두의 에이전트로 세션을 시작할 수 있어요. 상위 워크스페이스가 직접 운영하는 공용 앱 하나에만 쓰세요.
  • 하위 워크스페이스의 클라이언트용 키: 고객사마다 앱을 따로 배포한다면 고객사의 하위 워크스페이스에 키를 만들어 넣으세요. 키가 새도 그 고객사의 에이전트만 영향을 받아요.
  • 대시보드와 API의 구분: 상위 워크스페이스의 서버용 키는 대시보드에서만 관리해요. 이 API로 요청하면 403을 받고, 메시지에 type=publishable로 다시 시도하라는 안내가 붙어요.

클라이언트용 키 만들기

type에 publishable을 넣고 key_name을 정하세요. 이름은 64자까지예요. allowed_domains는 선택이고, 생략하면 어느 사이트에서나 쓸 수 있어요.
응답의 api_key가 pk_로 시작하는 클라이언트용 키예요. allowed_domains는 대시보드와 같은 규칙으로 정리돼요. 클라이언트용 키에 비어 있지 않은 allowed_ips를 보내거나 서버용 키에 비어 있지 않은 allowed_domains를 보내면 400 VALIDATION_ERROR가 와요. 빈 배열은 받아요.

목록 보기

클라이언트용 키는 항목마다 api_key 전체 값이 들어 있어요. type=all로 보면 서버용 키 항목의 api_key는 null이고, 서버용 키는 key_name과 secret_key_suffix(끝 4자리)만 보여요. 상위 워크스페이스 자신에게는 type=all도 403이라서 type=publishable로 조회하세요.

폐기하기

폐기할 키를 key_name과 secret_key_suffix로 가리키세요. 성공하면 204가 와요.
일치하는 키가 없으면 404 API_KEY_NOT_FOUND예요. 같은 종류에서 이름과 끝 4자리가 같은 키가 둘 이상이면 409 API_KEY_AMBIGUOUS가 오고 아무것도 지우지 않아요. 요청 필드는 API 키 발급, API 키 목록 조회, API 키 폐기에 있어요.

클라이언트용 키 바꾸기

허용 도메인을 바꾸거나 키를 새로 돌릴 때는 API로 고치지 말고 새 키로 갈아타세요. 키를 고치는 API는 없어요.
1

새 키 만들기

바꿀 allowed_domains로 type=publishable 키를 새로 만드세요. 이름은 이전 키와 달라야 구분돼요.
2

앱에 배포하기

SDK의 apiKey를 새 키로 바꿔 배포하고, 새 키로 세션이 시작되는지 확인하세요.
3

이전 키 폐기하기

이전 키의 key_name과 secret_key_suffix로 폐기하세요. 이전 키를 쓰는 앱이 남아 있지 않은지 먼저 확인하세요.

문제가 생겼을 때

Authorization: Bearer 뒤에 서버용 키(sk_) 전체를 넣었는지 확인하세요. sk_로 시작하지 않는 예전 서버용 키도 그대로 동작해요. 클라이언트용 키는 REST API에 쓸 수 없고, 삭제한 키나 삭제된 워크스페이스의 키도 거절돼요. 키가 속하지 않은 워크스페이스를 대상으로 요청하면 401이 아니라 403이나 404가 와요. 메인 워크스페이스 키는 직속 하위 워크스페이스를 대상으로 할 수 있어요.
응답의 오류 코드가 API_KEY_NOT_FOR_SESSIONS이면 클라이언트용 키를 만들어 SDK에 넣으세요. 클라이언트용 키가 나온 뒤에 만든 서버용 키는 브라우저와 모바일 앱에서 쓸 수 없어요.
CLIENT_KEY_INVALID(401)이면 키를 다시 복사하고 목록에 남아 있는지 보세요. CLIENT_KEY_ORIGIN_NOT_ALLOWED(403)이면 허용 도메인에 지금 사이트가 있는지 보세요. 개발 중이면 localhost도 넣으세요. 앱 전용 키는 허용 도메인을 비워 두세요.
잠시 뒤 다시 시작하세요. RATE_LIMIT_EXCEEDED(429)는 키와 IP마다 분당 30회를 넘은 경우예요. 같은 사무실이나 같은 네트워크의 방문자가 한 IP로 보이면 한도를 함께 써요.
같은 종류의 목록을 조회해 키가 만들어졌는지 보세요. 클라이언트용 키는 목록에서 api_key 전체 값을 다시 읽을 수 있어요. 서버용 키는 만들 때만 전체 값이 보이니, 목록에 이름만 있고 값을 받지 못했다면 그 키를 폐기하고 다시 발급하세요.
API_KEY_LIMIT_EXCEEDED이면 그 종류의 키가 이미 20개예요. 오류의 details.current로 지금 개수를 보고, 쓰지 않는 키를 먼저 폐기한 뒤 만드세요. 새 키가 필요한 교체라면 이전 키를 폐기한 다음 새 키를 만드세요.
상위 워크스페이스의 서버용 키를 이 API로 다루려는 경우일 수 있어요. 대시보드에서 관리하거나 type=publishable로 요청하세요. 하위 워크스페이스의 키로 상위 워크스페이스를 대상으로 삼아도 거절돼요. 클라이언트용 키(pk_)로는 이 API를 호출할 수 없어요.