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

# 인증

> 개발자 콘솔에서 API Key를 발급받고, 모든 Supertone API 요청에 `x-sup-api-key` 헤더로 인증합니다.

<Note>
  이 문서는 영어 원문을 기반으로 자동 번역되었습니다. 표현이 어색하거나 모호한 부분이 있을 수 있으니, 정확한 내용은 [영어 원문](/en/docs/authentication)을 함께 확인해 주세요.
</Note>

Supertone API는 커스텀 헤더로 전송된 API Key로 요청을 인증합니다. 키는 개발자 콘솔에서 발급되며 계정에 연결됩니다.

## 키 발급받기

1. [console.supertoneapi.com](https://console.supertoneapi.com)에 로그인합니다.
2. **API Keys**를 열고 **Create new key**를 클릭합니다.
3. 키를 복사합니다 — 키는 한 번만 표시됩니다. 소스 코드가 아닌 환경 변수로 저장하세요.

```bash theme={"dark"}
export SUPERTONE_API_KEY="Kp9mZ3xQ7v..."
```

<Note>
  계정당 최대 **3개의 활성 API Key**를 보유할 수 있습니다. 키가 노출된 경우 콘솔에서 폐기하고 재발급하세요.
</Note>

## 요청 인증하기

모든 호출의 요청 헤더 `x-sup-api-key`에 키를 포함하세요.

<Tabs>
  <Tab title="Python">
    SDK는 생성자에서 키를 읽어옵니다. 환경 변수와 연결하세요.

    ```python theme={"dark"}
    import os
    from supertone import Supertone

    client = Supertone(api_key=os.environ["SUPERTONE_API_KEY"])
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={"dark"}
    import { Supertone } from "@supertone/supertone";

    const client = new Supertone({ apiKey: process.env.SUPERTONE_API_KEY });
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={"dark"}
    curl https://supertoneapi.com/v1/voices \
      -H "x-sup-api-key: $SUPERTONE_API_KEY"
    ```
  </Tab>
</Tabs>

## 인증 오류

| Status             | When it happens                                                     |
| ------------------ | ------------------------------------------------------------------- |
| `401 Unauthorized` | `x-sup-api-key` 헤더가 누락되었거나 형식이 잘못되었거나, 활성 키와 일치하지 않습니다.             |
| `403 Forbidden`    | 키는 유효하지만 해당 리소스에 대한 권한이 없습니다 — 예를 들어, 다른 계정에 속한 클론드 보이스를 호출한 경우입니다. |

전체 오류 목록과 권장 대응은 [오류 처리](/ko/docs/production/error-handling)를 참고하세요.

## 보안 체크리스트

* **클라이언트 측 코드에 키를 절대 포함하지 마세요.** 모바일 앱, 싱글 페이지 앱, 브라우저 확장은 키를 보관하는 자체 백엔드를 통해 호출해야 합니다.
* **환경 변수**, 시크릿 매니저 또는 키 볼트 서비스를 사용하세요. 키를 git에 커밋하거나 로그에 출력하지 마세요.
* 키를 정기적으로 **로테이션**하고, 유출이 의심되면 즉시 콘솔에서 폐기·재발급한 뒤 재배포하세요.
* **서비스 단위로 분리하세요.** 여러 앱을 운영한다면 별도의 키를 발급해 사용량을 구분하고 개별적으로 폐기할 수 있도록 하세요.