BYOK 앱 등록·헤더 규약 (X-Bareun-App-Id)

BYOK(Bring Your Own Key)는 여러분이 만든 애플리케이션을 최종 사용자가 자신의 바른 API 키로 쓰게 하는 배포 방식입니다. 최종 사용자마다 자기 키를 넣고 쓰기 때문에 여러분(개발자)에게는 과금이 잡히지 않지만, 대신 "어느 앱이 얼마나 호출됐는지"를 사용자별 키 사용량만으로는 알 수 없습니다. X-Bareun-App-Id 헤더는 이 간극을 메웁니다.

핵심 아이디어: 키는 사용자 것, 앱 식별자는 개발자 것

graph LR
  U[최종 사용자] -- 자신의 koba- 키 --> A[여러분의 앱]
  A -- api-key: koba-... + X-Bareun-App-Id: app-... --> B[바른 클라우드]
  B --> L[(사용량 로그)]
  L --> D[앱 소유자가 /apps 에서 조회]

• API 키(koba-...)는 최종 사용자 소유이며 호출 인증·과금의 기준입니다.
• app_id(app-...)는 개발자가 bareun.ai에서 등록해 발급받는 공개 식별자입니다. 비밀값이 아닙니다 — 데스크톱/모바일 앱 배포판에 그대로 박히는 것을 전제로 설계했습니다.
• app_id는 집계·조회 전용입니다. 권한이나 과금 판단에는 쓰이지 않습니다. 즉 위조된 app_id를 보내도 호출 자체는 최종 사용자 키의 유효성만으로 정상 처리됩니다.

앱 등록 절차

1. 바른 계정으로 로그인한 뒤 bareun.ai/apps로 이동합니다.
2. 새 앱 등록을 눌러 앱 이름·설명·서비스 URL을 입력합니다.
3. 등록하면 app-2bnhvgi-2ine3zy 형태의 app_id가 발급됩니다. 화면에서 바로 복사할 수 있습니다.
4. 앱을 여러 개 운영한다면 계정당 여러 개 등록할 수 있습니다(앱 단위로 사용량이 갈립니다).
5. 더 이상 쓰지 않는 앱은 삭제 대신 비활성화로 전환합니다. 비활성화한 뒤에는 그 app_id로 들어오는 호출이 있어도 사용량 화면에 새로 집계되지 않습니다.

헤더 적용 방법

발급받은 app_id를 최종 사용자의 키로 호출할 때마다 X-Bareun-App-Id 헤더에 실어 보냅니다. api-key는 최종 사용자의 키를 그대로 씁니다 — app_id가 있다고 해서 User-Agent를 별도로 지정해 앱을 구분하라고 안내하지 않습니다. 앱 식별은 이 헤더 하나로 충분합니다.

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

REST(Connect)는 위처럼 일반 HTTP 헤더로 붙이면 됩니다. gRPC 기반 SDK(bareunpy 등)를 쓴다면 각 클라이언트가 제공하는 요청 메타데이터(gRPC metadata) 추가 방법으로 X-Bareun-App-Id 를 실어 보내세요 — 구체적인 API는 클라이언트별 통합 비교 문서와 각 SDK 버전의 문서를 참고하시기 바랍니다. 헤더 이름은 대소문자를 가리지 않습니다. gRPC 메타데이터는 키를 소문자로만 받으므로 x-bareun-app-id 로 적습니다.

서버가 받아들이는 값의 형식

서버는 헤더 값을 다음 규칙으로 확인한 뒤 사용량 로그에 기록합니다.

규칙에 어긋나는 값(공백 포함, 65자 이상, 한글이나 기호 등)은 헤더가 없는 것과 같이 처리합니다. 호출은 그대로 정상 처리되고, 다만 앱 단위 집계에는 잡히지 않습니다. bareun.ai/apps 에서 발급된 app_id 를 그대로 쓰면 이 규칙을 항상 만족합니다.

앱을 등록하면 무엇을 얻나요

• 함수별·일별 사용량 조회: /apps에서 앱별로 형태소분석·토크나이즈·맞춤법검사 등 기능별 호출량을 날짜별로 볼 수 있습니다. 그 app_id로 호출한 모든 최종 사용자의 사용량이 합산되어 잡히므로, 개별 사용자의 키 사용량을 일일이 추적하지 않아도 앱 전체의 실사용 규모를 파악할 수 있습니다.
• 사용자 식별은 노출되지 않습니다: 앱 소유자에게 보이는 것은 집계된 호출 수뿐이고, 어느 사용자의 키였는지는 표시하지 않습니다.
• app_id는 현재 단계에서 별도의 등급 상승(요청 한도 확대 등)을 주지 않습니다. 등록 여부와 무관하게 호출 자체는 각 최종 사용자 키의 정책을 그대로 따릅니다.

이용 조건

• 최종 사용자 본인 명의의 키만 쓰도록 안내해야 합니다.
• 최종 사용자 키로 호출할 때는 X-Bareun-App-Id 헤더를 반드시 함께 보냅니다.
• 등록한 앱을 통해 키를 재판매하거나 제3자와 공유하지 않습니다.
• 바른이 정한 속도 제한(rate limit) 등 이용 정책을 지킵니다.
• 키 관리 책임은 어디까지나 최종 사용자 본인에게 있습니다.

자세한 약관은 이용약관 제11조(제3자 앱을 통한 서비스 이용, BYOK)를 참고하세요.

자주 묻는 질문

Q. app_id도 API 키처럼 비밀로 관리해야 하나요?

아니요. app_id는 공개 식별자로 설계됐습니다. 데스크톱 앱 배포판이나 클라이언트 코드에 그대로 포함해도 됩니다. 다만 실제 인증·과금은 여전히 최종 사용자의 koba- 키가 담당하므로 그 키는 지금처럼 비밀로 관리해야 합니다.

Q. app_id를 안 보내거나 형식이 틀리면 어떻게 되나요?

호출 자체는 정상 처리됩니다. 다만 그 호출은 앱 단위 사용량 집계에 잡히지 않고, 최종 사용자의 전체 사용량에만 포함됩니다. 형식이 틀린 값(공백 포함, 64자 초과, 허용 문자 밖)도 헤더가 없는 것과 같이 다룹니다.

Q. 한 계정으로 앱을 여러 개 등록할 수 있나요?

네. 서비스별로 app_id를 나눠 등록하면 /apps에서 앱별 사용량을 따로 볼 수 있습니다.