> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryvox.co/llms.txt
> Use this file to discover all available pages before exploring further.

# API 키

> 서버와 앱에서 vox.ai를 호출할 API 키를 만들고 안전하게 보관할 수 있어요.

API 키는 외부 코드가 워크스페이스를 대신해 vox.ai를 쓸 때 내는 값이에요. 서버에서 REST API를 부르는 서버용 키와 브라우저나 모바일 앱에서 세션을 시작하는 클라이언트용 키, 두 가지가 있어요.

<img src="https://mintcdn.com/fleek/mz50K1phbq4VkAr7/images/screens/workspace/api-keys/list.webp?fit=max&auto=format&n=mz50K1phbq4VkAr7&q=85&s=700e843ca44c9775435e5b0d97558069" alt="설정의 API 키 목록. 이름, 종류, API 키, 생성일시, 마지막 사용이 보여요" style={{ borderRadius: "0.5rem" }} width="1668" height="470" data-path="images/screens/workspace/api-keys/list.webp" />

## API 키 종류 고르기

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

| 종류 | 쓰는 곳과 할 수 있는 일 | 보관 |
| - | - | - |
| 서버용(`sk_`) | REST API, CLI, Python SDK에서 워크스페이스의 REST API를 호출해요 | 서버에만 두세요. 만들 때 한 번만 보여요 |
| 클라이언트용(`pk_`) | 브라우저와 모바일 앱의 음성 SDK에서 세션 시작만 할 수 있어요. REST API는 호출할 수 없어요 | 앱 코드에 넣어도 돼요. 목록에서 언제든 복사할 수 있어요 |

## API 키 만들기

<Steps>
  <Step title="만들기 창 열기">
    **설정 > API 키**에서 **API 키 만들기**를 누르세요. 키를 만들고 삭제하는 일은 오너와 관리자가 해요.
  </Step>

  <Step title="이름과 용도 정하기">
    **API 키 이름**에 키를 구분할 이름을 64자 안으로 적고, **용도**에서 **서버용**이나 **클라이언트용**을 고르세요. 클라이언트용이면 **허용 도메인 (선택)** 항목도 정할 수 있어요. 설정은 [웹페이지와 모바일 앱 연결하기](#웹페이지와-모바일-앱-연결하기)에 있어요.
  </Step>

  <Step title="키 복사해 보관하기">
    **만들기**를 누르면 키가 나와요. **API 키 복사**를 눌러 서버용 키는 서버의 환경 변수 `VOX_API_KEY`에 저장하세요. 서버용 키는 이 창을 닫으면 다시 볼 수 없어요.
  </Step>

  <Step title="목록에서 확인하기">
    목록의 **종류**, **API 키**, **마지막 사용**으로 키를 구분하세요. 서버용 키는 끝 4자리만 보이고, 클라이언트용 키는 가운데를 줄여서 보여 줘요.
  </Step>
</Steps>

<img src="https://mintcdn.com/fleek/mz50K1phbq4VkAr7/images/screens/workspace/api-keys/created.webp?fit=max&auto=format&n=mz50K1phbq4VkAr7&q=85&s=87fae41bdc8a4796ade004efc527d985" alt="API 키를 만든 직후 키가 한 번만 보이는 창" style={{ maxWidth: "480px", margin: "0 auto", borderRadius: "0.5rem" }} width="896" height="490" data-path="images/screens/workspace/api-keys/created.webp" />

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

브라우저와 모바일 앱의 음성 SDK에는 클라이언트용 키를 넣으세요. **용도**에서 **클라이언트용**을 골라 키를 만들고, 목록에서 `pk_` 키를 복사해 SDK의 `apiKey`에 넣으세요. 사용법은 [JavaScript](/docs/sdk/javascript)와 [React](/docs/sdk/react)에 있어요.

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

<Note>
  `pk_`로 보낸 `external_id`는 브라우저가 주장한 값이에요. [고객 메모리](/docs/build/customer-memory/memory)를 쓰는 에이전트에는 `pk_`와 `external_id`를 함께 쓰지 마세요.
</Note>

## 문제가 생겼을 때

<AccordionGroup>
  <Accordion title="REST API 요청이 401로 거절돼요">
    `Authorization: Bearer` 뒤에 서버용 키(`sk_`) 전체를 넣었는지 확인하세요. `sk_`로 시작하지 않는 예전 서버용 키도 그대로 동작해요. 클라이언트용 키는 REST API에 쓸 수 없고, 삭제한 키와 다른 워크스페이스의 키도 거절돼요.
  </Accordion>

  <Accordion title="브라우저나 앱에서 서버용 키로 세션이 시작되지 않아요">
    응답의 오류 코드가 `API_KEY_NOT_FOR_SESSIONS`이면 클라이언트용 키를 만들어 SDK에 넣으세요. 클라이언트용 키가 나온 뒤에 만든 서버용 키는 브라우저와 모바일 앱에서 쓸 수 없어요.
  </Accordion>

  <Accordion title="클라이언트용 키가 거절돼요">
    `CLIENT_KEY_INVALID`(401)이면 키를 다시 복사하고 목록에 남아 있는지 보세요. `CLIENT_KEY_ORIGIN_NOT_ALLOWED`(403)이면 허용 도메인에 지금 사이트가 있는지 보세요. 개발 중이면 `localhost`도 넣으세요. 앱 전용 키는 허용 도메인을 비워 두세요.
  </Accordion>

  <Accordion title="세션 시작이 너무 잦다며 거절돼요">
    잠시 뒤 다시 시작하세요. `RATE_LIMIT_EXCEEDED`(429)는 키와 IP마다 분당 30회를 넘은 경우예요. 같은 사무실이나 같은 네트워크의 방문자가 한 IP로 보이면 한도를 함께 써요.
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.