API 키 종류 고르기
키를 쓸 곳에 맞춰 용도를 하나 고르세요. 용도는 만든 뒤 바꿀 수 없어요.API 키 만들기
1
만들기 창 열기
설정 > API 키에서 API 키 만들기를 누르세요. 키를 만들고 삭제하는 일은 오너와 관리자가 해요.
2
이름과 용도 정하기
API 키 이름에 키를 구분할 이름을 64자 안으로 적고, 용도에서 서버용이나 클라이언트용을 고르세요. 클라이언트용이면 허용 도메인 (선택) 항목도 정할 수 있어요. 설정은 웹페이지와 모바일 앱 연결하기에 있어요.
3
키 복사해 보관하기
만들기를 누르면 키가 나와요. API 키 복사를 눌러 서버용 키는 서버의 환경 변수
VOX_API_KEY에 저장하세요. 서버용 키는 이 창을 닫으면 다시 볼 수 없어요.4
목록에서 확인하기
목록의 종류, API 키, 마지막 사용으로 키를 구분하세요. 서버용 키는 끝 4자리만 보이고, 클라이언트용 키는 가운데를 줄여서 보여 줘요.
웹페이지와 모바일 앱 연결하기
브라우저와 모바일 앱의 음성 SDK에는 클라이언트용 키를 넣으세요. 용도에서 클라이언트용을 골라 키를 만들고, 목록에서pk_ 키를 복사해 SDK의 apiKey에 넣으세요. 사용법은 JavaScript와 React에 있어요.
- 허용 도메인 (선택): 키를 쓸 사이트를
example.com처럼 20개까지, 한 항목은 253자까지 넣을 수 있어요. 넣으면 그 사이트와 하위 도메인에서만 세션이 시작돼요. 비우면 어디서나 쓸 수 있어요. 모바일 앱은 도메인 정보를 보내지 않으니 앱 전용 키는 비워 두세요. - 세션 범위: 클라이언트용 키는 에이전트를 가리지 않아요. 키가 속한 워크스페이스의 어느 에이전트와 버전으로든 세션을 시작할 수 있으니, 허용 도메인으로 쓸 수 있는 사이트를 좁혀 두세요.
- 시작 한도: 키와 IP마다 분당 30회까지 세션을 시작할 수 있어요.
- 서버용 키: 클라이언트용 키가 나온 뒤에 만든 서버용 키는 브라우저와 모바일 앱에서 세션을 시작할 수 없어요. 그 전에 만든 서버용 키는 그대로 동작해요. 브라우저나 모바일 앱에 넣어 쓰던 서버용 키는 클라이언트용 키를 새로 만들어 바꾸고, 이전 키는 행 메뉴의 삭제로 지우세요.
pk_로 보낸 external_id는 브라우저가 주장한 값이에요. 고객 메모리를 쓰는 에이전트에는 pk_와 external_id를 함께 쓰지 마세요.문제가 생겼을 때
REST API 요청이 401로 거절돼요
REST API 요청이 401로 거절돼요
Authorization: Bearer 뒤에 서버용 키(sk_) 전체를 넣었는지 확인하세요. sk_로 시작하지 않는 예전 서버용 키도 그대로 동작해요. 클라이언트용 키는 REST API에 쓸 수 없고, 삭제한 키와 다른 워크스페이스의 키도 거절돼요.브라우저나 앱에서 서버용 키로 세션이 시작되지 않아요
브라우저나 앱에서 서버용 키로 세션이 시작되지 않아요
응답의 오류 코드가
API_KEY_NOT_FOR_SESSIONS이면 클라이언트용 키를 만들어 SDK에 넣으세요. 클라이언트용 키가 나온 뒤에 만든 서버용 키는 브라우저와 모바일 앱에서 쓸 수 없어요.클라이언트용 키가 거절돼요
클라이언트용 키가 거절돼요
CLIENT_KEY_INVALID(401)이면 키를 다시 복사하고 목록에 남아 있는지 보세요. CLIENT_KEY_ORIGIN_NOT_ALLOWED(403)이면 허용 도메인에 지금 사이트가 있는지 보세요. 개발 중이면 localhost도 넣으세요. 앱 전용 키는 허용 도메인을 비워 두세요.세션 시작이 너무 잦다며 거절돼요
세션 시작이 너무 잦다며 거절돼요
잠시 뒤 다시 시작하세요.
RATE_LIMIT_EXCEEDED(429)는 키와 IP마다 분당 30회를 넘은 경우예요. 같은 사무실이나 같은 네트워크의 방문자가 한 IP로 보이면 한도를 함께 써요.