BYOK app registration and header convention (X-Bareun-App-Id)

BYOK (Bring Your Own Key) is a distribution model in which end users run the application you built with their own Bareun API key. Each end user enters and uses their own key, so no charges are billed to you (the developer), but in exchange you cannot tell "how much each app was called" from per-user key usage alone. The X-Bareun-App-Id header fills this gap.

Core idea: the key belongs to the user, the app identifier belongs to the developer

graph LR
  U[End user] -- their own koba- key --> A[Your app]
  A -- api-key: koba-... + X-Bareun-App-Id: app-... --> B[Bareun Cloud]
  B --> L[(Usage log)]
  L --> D[App owner views it at /apps]

• The API key (koba-...) belongs to the end user and is the basis for call authentication and billing.
• The app_id (app-...) is a public identifier that the developer registers and gets issued at bareun.ai. It is not a secret. It was designed on the assumption that it is embedded as is in desktop and mobile app builds.
• The app_id is for aggregation and lookup only. It is not used for authorization or billing decisions. In other words, even if a forged app_id is sent, the call itself is processed normally based only on the validity of the end user's key.

App registration steps

1. Log in with your Bareun account and go to bareun.ai/apps.
2. Click Register new app and enter the app name, description, and service URL.
3. After registration, an app_id in the form app-2bnhvgi-2ine3zy is issued. You can copy it right from the screen.
4. If you run several apps, you can register multiple apps per account (usage is split per app).
5. For an app you no longer use, deactivate it instead of deleting it. After you deactivate it, calls that still come in with that app_id are no longer newly counted on the usage screen.

How to apply the header

Send the issued app_id in the X-Bareun-App-Id header on every call made with an end user's key. For api-key, use the end user's key as is. We do not instruct you to distinguish apps by setting a separate User-Agent just because you have an app_id. This one header is enough to identify the app.

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"}}'

For REST (Connect), attach it as an ordinary HTTP header as shown above. If you use a gRPC-based SDK (such as bareunpy), send X-Bareun-App-Id using the way each client provides to add request metadata (gRPC metadata). For the specific API, see the client integration comparison page and the documentation for each SDK version. Header names are case-insensitive. gRPC metadata accepts only lowercase keys, so write it as x-bareun-app-id.

The value format the server accepts

The server checks the header value with the following rules and then records it in the usage log.

A value that breaks the rules (containing whitespace, 65 or more characters, Korean characters or symbols, and so on) is handled as if the header were absent. The call is still processed normally, but it does not show up in per-app aggregation. If you use the app_id issued at bareun.ai/apps as is, it always satisfies these rules.

What do you get by registering an app?

• Per-function, per-day usage lookup: At /apps, you can see the call volume for each feature, such as morphological analysis, tokenization, and spell checking, by date for each app. The usage of all end users who called with that app_id is summed up, so you can see the actual scale of use of the whole app without tracking each individual user's key usage.
• User identity is not exposed: All the app owner sees is the aggregated number of calls. Which user's key it was is not shown.
• At this stage, an app_id does not grant any tier upgrade (such as a higher request limit). Regardless of whether you register, the call itself follows the policy of each end user's key as is.

Terms of use

• You must direct end users to use only keys issued in their own name.
• When you call with an end user's key, always send the X-Bareun-App-Id header with it.
• Do not resell keys or share them with third parties through a registered app.
• Comply with the usage policies set by Bareun, such as rate limits.
• Responsibility for key management rests entirely with the end user.

For the full terms, see Terms of Service, Article 11 (Use of the service through third-party apps, BYOK).

Frequently asked questions

Q. Do I have to keep the app_id secret like an API key?

No. The app_id is designed as a public identifier. You can include it as is in a desktop app build or in client code. However, actual authentication and billing are still handled by the end user's koba- key, so keep that key secret as you do now.

Q. What happens if I do not send the app_id or its format is wrong?

The call itself is processed normally. However, that call is not counted in the per-app usage aggregation and is included only in the end user's overall usage. A value in the wrong format (containing whitespace, longer than 64 characters, or with characters outside the allowed set) is also treated as if the header were absent.

Q. Can I register multiple apps with one account?

Yes. If you register a separate app_id for each service, you can view usage per app separately at /apps.