Authentication and API Keys
Koldan uses token-based authentication for all API requests. Every call to a protected endpoint must include a valid credential in the request headers. Two authentication methods are supported: OAuth2 Bearer tokens (JWT) and API Keys.
Authentication Methods
OAuth2 Bearer Token (JWT)
Interactive applications (web UIs, desktop clients) authenticate using OAuth2 / OpenID Connect. After a user signs in through the configured identity provider, the client receives a JWT access token.
Include the token in the Authorization header:
GET /api/v1/transcriptions HTTP/1.1
Host: koldan.dixilang.com
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...
Token lifecycle
- Tokens are issued and refreshed through your identity provider (IdP).
- Koldan validates the token signature against the tenant's OIDC JWK set - it never stores passwords.
- When a token expires, use the refresh-token flow to obtain a new one.
API Key
For server-to-server integrations, scripts, and automated workflows, API Keys provide a simpler alternative that doesn't require an OAuth flow.
Include the key in the X-API-Key header:
POST /api/v1/transcriptions HTTP/1.1
Host: koldan.dixilang.com
X-API-Key: kk-a1b2c3d4e5f6g7h8i9j0...
API Key takes priority
If both Authorization and X-API-Key headers are present in the same request, the API Key is used and the Bearer token is ignored.
How API Keys Work
Key Format
All API keys share a recognizable format:
| Part | Example | Description |
|---|---|---|
| Prefix | kk- |
Fixed prefix that identifies the string as a Koldan API key |
| Secret | a1b2c3d4e5... (64 characters) |
Randomly generated secret, hashed before storage |
Full key example: kk-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2
Store your key immediately
The plain-text key is returned only once - at creation time. Koldan stores a one-way hash and cannot retrieve the original key. If you lose it, revoke the old key and create a new one.
Key Lifecycle
When creating an API key, you provide a name and optionally a description, expiration date, and a set of scopes. The full API key is shown once in the response - store it securely.
An API key can be in one of three states:
| State | Can Authenticate? | Description |
|---|---|---|
| Active | Key is valid and has not expired or been revoked | |
| Expired | Current time is past the key's expiration date | |
| Revoked | Key was explicitly revoked by the user or an administrator |
Revocation is permanent - once revoked, the key can never be used again.
For the full API reference on creating, listing, and revoking API keys, see API Keys API.
Scoped Permissions
How Scopes Work
Scopes control what an API key is allowed to do. There are two types of API keys:
- Scoped key - created with an explicit list of scopes. The requested scopes must be a subset of the creator's own role permissions. At runtime, the key's effective permissions are the intersection of its scopes and the user's current role permissions.
- Identity-only key - created without specifying scopes. The key provides authentication only (identifies the caller) but carries no authorization scopes. Requests to endpoints that require a specific scope will be rejected with
403 Forbidden.
For the complete list of available scopes and how they map to roles, see Roles and Permissions.
Identity-only keys have no permissions
If you create an API key without specifying any scopes, it will not inherit your role's permissions. It will only authenticate your identity. Always specify the scopes your integration needs.
Koldan Authentication Best Practices
- Use scoped keys - always limit API keys to the minimum scopes required for the task.
- Set expiration dates - prefer short-lived keys for CI/CD pipelines and automated scripts.
- Rotate regularly - create a new key, update your integration, then revoke the old one.
- Never commit keys - store API keys in environment variables or a secrets manager, not in source code.
- One key per integration - if a key is compromised, you can revoke it without affecting other systems.
- Use Bearer tokens for interactive apps - API Keys are designed for non-interactive, server-side use cases.