인증 및 키

인증 방식

모든 인터페이스는 Bearer Token 인증을 사용하며, 요청 헤더에 API 토큰을 포함합니다:

Authorization: Bearer sk-xxxxxxxxxxxxxxxx

토큰은 콘솔의 토큰(API Keys) 페이지에서 생성 및 관리합니다.

토큰 기능

토큰 생성 시 필요에 따라 구성할 수 있습니다:

구성 항목	설명
이름	용도를 구분하기 위한 이름 (예: prod-app, test)
한도 상한	해당 토큰이 소비할 수 있는 최대 한도, 초과 시 요청이 거부됨
만료 시간	만료 시 자동으로 무효화, 임시 인증에 적합
모델 그룹	토큰이 호출할 수 있는 모델 범위를 제한
IP 화이트리스트	허용된 호출 출처 IP를 제한 (선택 사항)

하나의 계정에서 여러 토큰을 생성할 수 있으며, 환경/프로젝트별로 분리하여 사용량 통계 및 회수를 용이하게 하는 것을 권장합니다.

보안 권장 사항

• 키는 서버 측 환경 변수 또는 키 관리 서비스에만 저장하고, 프론트엔드 코드나 공개 저장소에 절대 작성하지 마십시오;
• 프로젝트마다 다른 토큰을 사용하여, 유출 시 해당 토큰만 폐기하면 됩니다;
• 테스트용 토큰에는 작은 한도 상한과 만료 시간을 설정하십시오;
• 비정상적인 사용량이 감지되면, 먼저 콘솔에서 토큰을 비활성화한 후 호출 출처를 조사하십시오.

일반적인 인증 오류

HTTP 상태	의미	처리 방법
401	키 누락 또는 유효하지 않음	Authorization 헤더와 키가 올바른지 확인
403	토큰이 비활성화됨 / 그룹에 해당 모델 접근 권한 없음	토큰 상태 및 모델 그룹 확인
429	속도 제한 초과 또는 한도 부족	속도 제한 및 429 참조