인증

API 요청에는 항상 Authorization 헤더에 API 키 하나를 담습니다.

Authorization: Bearer sk-popnow-3f9c0a…

다른 인증 방법은 없습니다. URL 쿼리 문자열에 넣은 키는 받지 않으며, popnow.ai 로그인 상태도 API에서는 통하지 않습니다.

예외가 하나 있습니다. /v1 아래의 OpenAI 호환 경로는 x-api-key 헤더에서도 키를 읽으므로 OpenAI 방식 클라이언트를 그대로 쓸 수 있습니다. 기본 /api/v1 경로는 Authorization만 읽습니다.

키 형식

키는 sk-popnow- 뒤에 소문자 16진수 48자가 붙은 형태입니다. 만든 뒤에는 API 콘솔에 앞부분 몇 글자만 보이므로, 잃어버린 키는 되찾을 수 없습니다. 새로 만들면 됩니다.

키 만들기

1. popnow.ai에 로그인해 API 콘솔을 엽니다.
2. Create key를 누르고 production-backend처럼 쓰임새가 드러나는 이름을 붙입니다.
3. 바로 복사하세요. 전체 키는 이때 한 번만 보입니다.

키는 여러 개를 동시에 가질 수 있습니다. 환경별·서비스별로 따로 두면 하나만 폐기해도 나머지는 영향을 받지 않습니다. 모든 키는 같은 크레딧 잔액을 씁니다.

키를 어디에 둘까

• 환경 변수나 플랫폼의 시크릿 저장소(POPNOW_API_KEY)에 두고 소스 코드에는 넣지 마세요.
• 브라우저, 모바일 앱처럼 다른 사람의 기기에서 실행되는 코드에는 절대 넣지 마세요. 키를 읽을 수 있는 사람은 누구나 내 크레딧을 쓸 수 있습니다. 내 서버를 중간에 두고 서버가 PopNow를 호출하게 하세요.
• 로그에도 남기지 마세요. 요청 헤더를 기록한다면 먼저 Authorization을 빼세요.

키가 할 수 있는 일 제한하기

키마다 API 콘솔에서 따로 제한을 걸 수 있습니다.

기본 상태의 키에는 제한도 한도도 없습니다. 운영용 키에는 꼭 필요한 범위만 허용하세요.

작업은 만든 키에 속합니다

recordInfo, retry, purge, 작업 목록, 사용량은 같은 키로 만든 작업만 봅니다. 같은 계정의 다른 키로 만든 작업은 없는 작업과 똑같이 404를 돌려줍니다. 웹사이트에서 시작한 생성도 어느 키에서도 보이지 않습니다. 계정 전체를 보려면 API 콘솔을 쓰세요.

키 교체

중단 없이 키를 바꾸는 방법:

1. 새 키를 만듭니다.
2. 기존 키를 쓰던 모든 곳에 배포합니다.
3. 콘솔에서 기존 키의 마지막 사용 시각이 더 이상 바뀌지 않는지 확인합니다.
4. 기존 키를 폐기합니다.

키가 유출됐다면

1. 즉시 폐기하세요. API 콘솔에서 폐기하면 다음 요청부터 적용됩니다.
2. 새 키를 만들어 배포하세요.
3. 어디에 쓰였는지 확인하세요. 콘솔의 로그와 사용량에 그 키가 만든 모든 작업이 남아 있습니다.
4. 새 키를 좁히세요. IP 허용 목록과 지출 한도를 거세요.

본인이 쓰지 않은 지출이 보이면 고객 지원에 연락해 주세요.

실패 응답

세 가지 인증 문제 모두 HTTP 401, code: 401을 돌려주며 msg로 구분합니다.

유효한 키라도 403으로 거부될 수 있습니다. 예를 들어 계정 이메일이 아직 인증되지 않았을 때(40310)입니다. 오류를 참고하세요.