API key issuance, rotation, and expiry: an operations guide
You need an API key to call the Bareun API.
An API key is a string that starts with koba- (koba-XXXX-...),
and it is used to identify and authenticate the caller, both on the cloud (api.bareun.ai:443) and on installed (self-hosted) servers.
This page covers the operational flow from issuing a key to rotating it and handling expiry.
Where do I get a key?
| Environment | How to get one | Notes |
|---|---|---|
| Cloud | Issued at bareun.ai | Free tier of 50,000 eojeols (space-delimited word units) |
| Self-hosted | Use the server's API key registration procedure | Operated relative to BAREUN_ROOT |
For the cloud, get a key from the API key page on bareun.ai
and set the koba- key in your client.
How to apply a key
Put the issued key into each client as follows.
from bareunpy import Tagger
# Pass the issued koba- key as is.
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"}}'
If your app will be used with other people's keys
If you let end users use the app you built with their own keys (BYOK), send the X-Bareun-App-Id header, which identifies the app, along with the key. For how to get one and the conventions, see
BYOK app registration and header conventions.
Key rotation flow
Rotate the key when you suspect it has leaked or when you apply a periodic security policy. To switch without downtime, the safe order is to apply the new key first and then revoke the old key.
graph LR N[Issue a new key] --> A[Deploy the new key to clients] A --> V[Confirm calls succeed with the new key] V --> R[Revoke the old key]
- Issue a new key: Issue an additional key at
bareun.ai. - Roll out gradually: Apply the new key to your clients (server environment variables and secrets).
- Verify: Confirm that calls succeed with the new key.
- Revoke: Revoke the old key after all clients have moved over.
Managing expiry and limits
- Free tier: The cloud is free up to 50,000 eojeols. Usage beyond that follows the paid policy.
- Authentication errors in responses: If a key has expired, been revoked, or has the wrong format, it is rejected at the authentication step.
First check the key value and format (starts with
koba-) and the call address (api.bareun.ai:443). - Research use: There is a procedure that allows free use for the duration of the research once research use is confirmed.
Keys are secrets
Do not leave koba- keys in plain text in code, logs, or version control.
Inject them through environment variables or a secrets manager. When rotating, follow the order of applying the new key, verifying, then revoking the old key, and you can switch without interrupting calls.
Frequently asked questions
Q. What format is an API key?
A Bareun API key is a string that starts with koba- (koba-XXXX-...).
Set this value in the client as is to authenticate the caller.
Q. How do I replace a key without downtime?
Issue the new key first and deploy it to your clients, confirm that calls succeed with the new key, and then revoke the old key. If you follow this order, calls are not interrupted.
Q. How much can I use for free?
The cloud provides a free tier of up to 50,000 eojeols. Once research use is confirmed, a separate procedure allows free use for the duration of the research.