API 키와 보안

키는 어디서 만드나요?

대시보드 → API Keys에서 만듭니다. 키는 생성할 때 한 번만 표시되므로 바로 복사하세요.

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

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

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

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

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

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

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

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

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

먼저 대시보드 → API Keys에서 키를 폐기한 다음, 새 키를 만들어 해당 키를 쓰던 곳을 업데이트하세요. 폐기는 즉시 적용됩니다.

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

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

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

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

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

BeatAPI는 고객의 요청으로 학습하지 않습니다. 얼굴, 음성 등 개인 정보를 보내거나 다른 사람을 대신해 처리하기 전에 개인정보 처리방침과 서비스 약관을 확인하세요.

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

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

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