프리픽스와 그룹 구분자를 가진 API 키 포맷을 빠르게 검토

API 키 포맷을 정할 때 고려할 점

• 프리픽스(`sk_live_`, `pk_test_`)로 환경 구분 시각화
• 로그에 노출돼도 식별이 가능하도록 접두사만 남기는 truncate 전략
• checksum 추가로 오타 감지 가능 — 다만 이 도구에서는 기본값에 미포함
• 최소 128비트 이상의 엔트로피를 유지

안전한 API 키의 조건 — 길이가 곧 엔트로피

API 키의 보안 강도는 prefix가 아니라 랜덤 본문에서 나옵니다. 문자 집합 크기를 C, 본문 길이를 L이라 하면 엔트로피는 L × log₂(C) 비트입니다. 대문자+소문자+숫자(62자) 조합에서 길이 32면 약 190비트로, 무차별 대입이 사실상 불가능한 수준입니다.

일반적인 권장 기준은 128비트 이상입니다. 62자 문자 집합 기준으로 본문 길이 22자 이상이면 충족하고, 혼동 문자를 제외해 문자 집합이 줄어도 길이를 2~3자 늘리면 같은 강도를 유지합니다.

prefix 규칙 — 유출 탐지의 핵심

Stripe의 sk_live_ / sk_test_, GitHub의 ghp_ 처럼 서비스와 환경을 식별하는 prefix는 단순한 가독성 장치가 아닙니다. 고유한 prefix가 있으면 GitHub secret scanning 같은 도구가 커밋에 섞여 들어간 키를 패턴으로 탐지해 자동 폐기할 수 있습니다.

운영 키와 테스트 키는 반드시 prefix로 구분하세요. 로그나 에러 메시지에 키 일부가 남았을 때도 어떤 환경의 키가 노출됐는지 즉시 판단할 수 있습니다.

저장·운영 체크리스트

• 서버에는 키 원문 대신 해시(SHA-256)를 저장하고, 원문은 발급 시 한 번만 보여주기
• 키마다 만료일과 마지막 사용 시각을 기록해 미사용 키를 주기적으로 폐기
• 코드·설정 파일에 하드코딩 금지 — 환경 변수 또는 시크릿 매니저 사용
• 유출 시 즉시 폐기할 수 있도록 키 교체(rotation) 절차를 미리 마련

자주 묻는 질문

Q. 생성된 API 키는 서버로 전송되나요? 아니요. 모든 키는 브라우저의 Web Crypto API(crypto.getRandomValues)로 로컬에서 생성되며, 어떤 값도 서버로 전송되지 않습니다.

Q. API 키 길이는 얼마가 적당한가요? 랜덤 본문 기준 22자(약 128비트) 이상을 권장합니다. 외부에 공개되는 키라면 32자(약 190비트)로 여유를 두는 편이 안전합니다.

Q. UUID를 API 키로 써도 되나요? UUID v4는 122비트 엔트로피라 하한선은 넘지만, prefix를 붙일 수 없고 형식이 널리 알려져 있어 secret scanning 탐지에 불리합니다. 전용 포맷의 랜덤 키를 권장합니다.

Q. 이 도구로 만든 키를 운영 환경에 써도 되나요? 생성 자체는 암호학적으로 안전한 난수를 사용하므로 가능합니다. 다만 운영 키는 발급·폐기 이력이 남는 서버 측 발급 체계를 갖추는 것이 좋고, 이 도구는 포맷 설계와 스테이징·테스트 용도에 가장 적합합니다.

함께 쓰기 좋은 도구

같은 워크플로에서 바로 이어 쓸 수 있는 JSON2Class 도구를 연결해 두었습니다.