API 키는 프로그램용 비밀번호와 같습니다. 동시에 지출 권한이기도 합니다. 키를 가진 사람은 누구나 내 잔액을 쓸 수 있습니다.
작동 방식
LLM API는 키를 bearer 토큰으로 취급합니다. 클라이언트는 요청할 때마다 키를 보냅니다.
curl https://inference.broadnet.ai/v1/models \
-H "Authorization: Bearer $BROADNET_API_KEY"
RFC 6750은 bearer 토큰을 “any party in possession of the token”(번역: 토큰을 가진 모든 당사자)이 사용할 수 있는 토큰으로 정의합니다. 두 번째 인증 요소는 없습니다. 그래서 같은 RFC는 클라이언트가 bearer 토큰을 항상 TLS(https://)로 보내야 한다고 규정합니다.
제공업체는 키를 조회해 계정을 찾고, 한도와 정책을 확인한 다음 요청을 처리하거나 거부합니다. 키가 없거나 틀리면 보통 401을 반환하고, IP 허용 목록 같은 정책에 따라 거부된 키는 보통 403을 반환합니다.
왜 중요한가
봇이 공개 코드에서 비밀 정보를 스캔하기 때문에, 키 유출은 API 요금이 걷잡을 수 없이 불어나는 가장 흔한 원인 중 하나입니다. 키가 계정 정보를 반환하는 엔드포인트에 접근할 수 있다면 데이터가 노출될 수도 있습니다. OWASP 시크릿 관리 지침에 맞는 좋은 관행은 다음과 같습니다.
- 키는 환경 변수나 시크릿 관리 도구에서 불러오세요. 절대 커밋하거나 컨테이너 이미지에 넣지 마세요.
- 앱이나 에이전트마다 별도의 키를 주세요. 그래야 전체를 멈추지 않고 하나만 폐기할 수 있습니다.
- 키는 정기적으로, 그리고 유출이 의심되면 즉시 교체하세요.
- 서버 IP 허용 목록 등으로 키가 동작하는 위치를 제한하세요.
BroadNet Inference에서는
BroadNet은 두 가지 자격 증명을 구분합니다. 추론 키는 /v1/*에서 모델을 호출합니다. 포털 자격 증명은 키, 허용 IP, 구매 등 계정 관리를 자동화합니다. 포털 자격 증명은 계정 전체 권한으로 취급하세요.
둘 다 한 번만 표시됩니다. BroadNet은 SHA-256 해시만 보관하므로 키를 다시 보여 줄 수 없습니다. 종량제 키는 1년 동안 유효하며, 계정 하나에 유효한 키를 최대 10개까지 둘 수 있습니다. 키마다 허용 IP 목록을 따로 지정할 수 있습니다. 키를 폐기하거나 허용 목록을 변경하면 5초 안에 새 요청이 차단됩니다.
정액 플랜의 플랜 키는 별도이며 잔액에서 차감되지 않습니다. 설정 방법은 API 키와 IP 허용 목록에, 상태 코드는 오류와 재시도에 있습니다.
흔한 실수
- 요청 헤더 전체를 로그로 남기는 것. 키가 로그에 기록됩니다.
- 팀 전체가 키 하나를 공유하는 것. 한 사람의 접근만 폐기할 수 없게 됩니다.
- 지원팀에 키를 보내는 것. 대신
X-Request-ID헤더 값을 보내세요.