API 키 발급·회전·만료 운영 가이드

바른 API를 호출하려면 API 키가 필요합니다. API 키는 koba-로 시작하는 문자열(koba-XXXX-...) 형태이며, 클라우드(api.bareun.ai:443)와 설치본 모두에서 호출자를 식별·인증하는 데 쓰입니다.

이 문서는 키 발급부터 회전, 만료 대응까지의 운영 흐름을 정리합니다.

키는 어디서 발급하나요

환경	발급 경로	비고
클라우드	`bareun.ai`에서 발급	무료 구간 50,000 어절 제공
설치본	서버의 API 키 등록 절차 사용	`BAREUN_ROOT` 기준 운영

클라우드는 bareun.ai의 API 키 페이지에서 발급받아 koba- 키를 클라이언트에 설정하시면 됩니다.

키 적용 방법

발급한 키는 클라이언트별로 다음처럼 넣습니다.

from bareunpy import Tagger
# 발급받은 koba- 키를 그대로 전달합니다.
tagger = Tagger("koba-XXXX-...", host="api.bareun.ai", port=443)

curl -s -X POST https://api.bareun.ai/bareun.LanguageService/AnalyzeSyntax \
  -H "Content-Type: application/json" \
  -H "api-key: koba-XXXX-..." \
  -d '{"document":{"content":"안녕하세요.","language":"ko_KR"}}'

내 앱을 다른 사람의 키로 쓰게 한다면

여러분이 만든 앱을 최종 사용자가 각자의 키로 쓰게 하는 방식(BYOK)이라면, 키와 별개로 앱을 식별하는 X-Bareun-App-Id 헤더를 함께 보내세요. 발급 방법과 규약은 BYOK 앱 등록·헤더 규약을 참고하세요.

키 회전 흐름

키 유출이 의심되거나 주기적 보안 정책을 적용할 때는 키를 회전합니다. 무중단으로 옮기려면 새 키를 먼저 적용한 뒤, 옛 키를 폐기하는 순서가 안전합니다.

graph LR
  N[새 키 발급] --> A[클라이언트에 새 키 배포]
  A --> V[새 키로 정상 호출 확인]
  V --> R[옛 키 폐기]

새 키 발급: bareun.ai에서 추가 키를 발급합니다.
점진 배포: 클라이언트(서버 환경변수·시크릿)에 새 키를 적용합니다.
검증: 새 키로 호출이 정상인지 확인합니다.
폐기: 모든 클라이언트가 옮겨간 뒤 옛 키를 폐기합니다.

만료·한도 관리

무료 구간: 클라우드는 50,000 어절까지 무료입니다. 초과 사용은 유료 정책을 따릅니다.
응답 인증 오류: 키가 만료·폐기되었거나 형식이 틀리면 인증 단계에서 거부됩니다. 키 값과 형식(koba-로 시작), 호출 주소(api.bareun.ai:443)를 먼저 확인하세요.
연구 목적: 연구 목적 사용이 확인되면 연구 기간 동안 무료 사용을 허용하는 절차가 있습니다.

키는 비밀입니다

koba- 키는 코드·로그·버전 관리에 평문으로 남기지 마세요. 환경변수나 시크릿 매니저로 주입하고, 회전 시에는 새 키 적용 → 검증 → 옛 키 폐기 순서를 지키면 호출 중단 없이 교체할 수 있습니다.

자주 묻는 질문

Q. API 키는 어떤 형식인가요?

바른 API 키는 koba-로 시작하는 문자열(koba-XXXX-...)입니다. 클라이언트에 이 값을 그대로 설정해 호출자를 인증합니다.

Q. 키를 무중단으로 교체하려면 어떻게 하나요?

새 키를 먼저 발급해 클라이언트에 배포하고, 새 키로 정상 호출을 확인한 뒤 옛 키를 폐기하세요. 이 순서를 지키면 호출이 끊기지 않습니다.

Q. 무료로 얼마나 쓸 수 있나요?

클라우드는 50,000 어절까지 무료 구간을 제공합니다. 연구 목적 사용이 확인되면 연구 기간 동안 무료로 쓸 수 있도록 별도 절차로 허용합니다.