> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.beatapi.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server.

# API 키와 보안

> BeatAPI 키의 생성, 범위 지정, 교체, 폐기 방법과 키를 절대 두면 안 되는 위치를 설명합니다.

# API 키와 보안

## 키는 어디서 만드나요?

[대시보드 → API Keys](https://beatapi.io/dashboard/apikeys)에서 만듭니다. 키는 생성할 때 한 번만 표시되므로 바로 복사하세요.

## 키는 몇 개가 필요한가요?

BeatAPI를 호출하는 대상마다 하나씩 사용하세요. 애플리케이션, 도구, 환경마다 따로 발급합니다.

비용은 들지 않고 효과는 바로 나타납니다. 별도 계측 없이 `GET /v1/usage`의 `by_api_key`에서 지출이 구분되고, 유출되거나 이상하게 동작하는 키만 다른 서비스에 영향 없이 폐기할 수 있습니다.

개발, 스테이징, 프로덕션 환경끼리 키를 절대 공유하지 마세요.

## 키를 절대 두면 안 되는 곳은 어디인가요?

사용자나 제3자가 읽을 수 있는 모든 곳입니다.

* 브라우저 JavaScript나 클라이언트 측 번들. 브라우저로 전달되는 것은 모두 공개됩니다.
* 모바일 애플리케이션. 디컴파일은 흔한 일입니다.
* 공개 저장소, 또는 나중에 공개될 수 있는 비공개 저장소.
* 로그, 오류 보고서, 스크린샷, 지원 티켓.
* URL 쿼리 문자열. 프록시, 브라우저 기록, 서버 로그에 남습니다.

올바른 위치는 헤더뿐입니다: `Authorization: Bearer <key>`.

## 키가 저장소에 들어가지 않게 하려면 어떻게 하나요?

환경 변수를 사용하고, 값을 설정하는 파일은 버전 관리에서 제외하세요.

```bash
read -rsp "BeatAPI API key: " BEATAPI_API_KEY && echo
export BEATAPI_API_KEY
```

이렇게 읽으면 셸 기록에도 남지 않습니다. `.env`, `~/.codex/auth.json` 그리고 키가 들어 있는 도구 설정 파일을 `.gitignore`에 추가하세요.

지원하는 연동에서는 설정 파일에 키를 붙여 넣기보다 환경 변수 옵션을 사용하세요. [Codex CLI](/integrations/codex-cli)가 `env_key`를 지원하는 이유도 바로 이것입니다.

## 키가 유출되면 어떻게 하나요?

먼저 [대시보드 → API Keys](https://beatapi.io/dashboard/apikeys)에서 키를 폐기한 다음, 새 키를 만들어 해당 키를 쓰던 곳을 업데이트하세요. 폐기는 즉시 적용됩니다.

반드시 이 순서를 지키세요. 먼저 교체하고 나중에 폐기하면, 그사이 유출된 키가 잔액을 계속 사용할 수 있습니다.

그다음 `GET /v1/usage`의 `by_api_key`에서 알 수 없는 사용 내역이 있는지 확인하세요.

## 키는 얼마나 자주 교체해야 하나요?

실제로 지킬 수 있는 주기로 교체하고, 접근 권한이 있던 사람이 떠나거나 키가 노출되었을 가능성이 있으면 즉시 교체하세요. 구성 요소별로 키를 나누면 각 키가 배포 하나에만 연결되므로 교체 부담이 적습니다.

## 브라우저에서 BeatAPI를 직접 호출할 수 있나요?

API 키로는 안 됩니다. Realtime API의 경우 서버가 세션을 만들고, 그 세션으로 범위가 제한된 수명이 짧은 `client_secret`을 브라우저에 전달합니다. [실시간 API](/realtime-api)를 참고하세요. 그 밖의 모든 엔드포인트는 서버에서만 호출해야 합니다.

생성된 미디어는 읽기에 한해 예외입니다. 작업 결과물 URL에는 쿼리 문자열에 자체 서명된 자격 증명이 들어 있어 해당 객체 하나에만 접근 권한을 주므로, 브라우저가 헤더 없이 `<img>`나 `<video>`로 불러올 수 있습니다.

## 내 데이터가 학습에 사용되나요?

BeatAPI는 고객의 요청으로 학습하지 않습니다. 얼굴, 음성 등 개인 정보를 보내거나 다른 사람을 대신해 처리하기 전에 [개인정보 처리방침](https://beatapi.io/privacy-policy)과 [서비스 약관](https://beatapi.io/terms-of-service)을 확인하세요.

## 웹훅이 실제로 BeatAPI에서 왔는지 어떻게 확인하나요?

JSON을 파싱하기 전에 **원본 요청 바이트**로 서명을 검증하세요. 본문을 다시 직렬화하면 내용이 바뀌어 서명이 일치하지 않습니다. 오래된 전달이 재전송(replay)되지 않도록 타임스탬프도 확인하세요. [웹훅](/webhooks)을 참고하세요.

검증하지 않는 웹훅 엔드포인트는 인증 없이 시스템에 데이터를 쓸 수 있는 통로입니다. 검증에 실패하면 버그가 아니라 공격으로 간주하세요.

## 어떤 내용이 기록되나요?

요청은 지원과 과금을 위해 `request_id`와 함께 기록됩니다. 문제를 신고할 때는 키 자체가 아니라 이 ID를 알려 주세요.