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...

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...

Authentication API Reference

Authenticate users with the Koldan platform via username/password credentials, OAuth 2.0 authorization codes (with optional PKCE), token refresh, and logout. All endpoints delegate to the configured OIDC identity provider and return standard OAuth 2.0 token responses.

Public - No authentication required

Base path: /api/v1/auth

Login

POST /api/v1/auth/login

Authenticate a user with username and password credentials. On success, the OIDC provider issues an OAuth 2.0 token set (access token, refresh token, and optional ID token). The access token should be used as a Bearer token in subsequent API requests.

LoginRequest

{
  "username": "john.doe",
  "password": "s3cur3P@ssw0rd"
}

curl -X POST https://koldan.dixilang.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "john.doe",
    "password": "s3cur3P@ssw0rd"
  }'

import requests

resp = requests.post(
    "https://koldan.dixilang.com/api/v1/auth/login",
    json={
        "username": "john.doe",
        "password": "s3cur3P@ssw0rd"
    }
)
print(resp.json())

OAuthTokenResponse

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 300,
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "scope": "openid profile email"
}

Logout

POST /api/v1/auth/logout

Log out a user by invalidating their refresh token with the OIDC provider. After logout, the refresh token can no longer be used to obtain new access tokens.

LogoutRequest

{
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

curl -X POST https://koldan.dixilang.com/api/v1/auth/logout \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'

import requests

resp = requests.post(
    "https://koldan.dixilang.com/api/v1/auth/logout",
    json={
        "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
    }
)
print(resp.text)

Response

Exchange Authorization Code

POST /api/v1/auth/exchange-auth-code

Exchange an OAuth 2.0 authorization code for an access token using the Authorization Code with PKCE flow. The codeVerifier is required to complete the token exchange securely.

UnifiedLoginRequest

{
  "code": "abc123-authorization-code",
  "redirectUri": "https://app.example.com/callback",
  "codeVerifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
}

curl -X POST https://koldan.dixilang.com/api/v1/auth/exchange-auth-code \
  -H "Content-Type: application/json" \
  -d '{
    "code": "abc123-authorization-code",
    "redirectUri": "https://app.example.com/callback",
    "codeVerifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
  }'

import requests

resp = requests.post(
    "https://koldan.dixilang.com/api/v1/auth/exchange-auth-code",
    json={
        "code": "abc123-authorization-code",
        "redirectUri": "https://app.example.com/callback",
        "codeVerifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
    }
)
print(resp.json())

OAuthTokenResponse

Returns an OAuthTokenResponse object (see field table in Login).

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 300,
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "scope": "openid profile email"
}

Refresh Token

POST /api/v1/auth/refresh-token

Refresh an expired access token using a valid refresh token. Returns a new OAuth 2.0 token set with a fresh access token.

RefreshTokenRequest

{
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

curl -X POST https://koldan.dixilang.com/api/v1/auth/refresh-token \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'

import requests

resp = requests.post(
    "https://koldan.dixilang.com/api/v1/auth/refresh-token",
    json={
        "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
    }
)
print(resp.json())

OAuthTokenResponse

Returns an OAuthTokenResponse object (see field table in Login).

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 300,
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "scope": "openid profile email"
}

Authentication Flows

Koldan supports multiple authentication flows depending on your application type:

Direct Login (Resource Owner Password)

The simplest flow for server-side applications and scripts. Send the user's credentials directly to the Login endpoint.

sequenceDiagram
    participant C as Client
    participant K as Koldan API
    participant O as OIDC Provider

    C->>K: POST /api/v1/auth/login<br>{ username, password }
    K->>O: Token Request
    O-->>K: OAuthTokenResponse
    K-->>C: 200 OK { access_token, … }

Authorization Code Flow with PKCE

Recommended for browser-based and mobile applications. The user authenticates directly with the OIDC provider and your application exchanges the resulting authorization code for tokens using PKCE.

sequenceDiagram
    participant U as User
    participant A as Client App
    participant O as OIDC Provider
    participant K as Koldan API

    U->>A: Login
    A->>A: Generate code_verifier & code_challenge
    A->>O: Redirect to /authorize<br>with code_challenge
    U->>O: Authenticate with provider
    O-->>U: Authenticated
    O-->>A: Redirect with ?code=abc123
    A->>K: POST /api/v1/auth/exchange-auth-code<br>{ code, redirectUri, codeVerifier }
    K-->>A: 200 OK { access_token, … }

Using Tokens

Once authenticated, include the access token in the Authorization header of all API requests:

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

curl -X GET https://koldan.dixilang.com/api/v1/some-resource \
  -H "Authorization: Bearer $JWT"

import requests

resp = requests.get(
    "https://koldan.dixilang.com/api/v1/some-resource",
    headers={"Authorization": f"Bearer {JWT}"}
)
print(resp.json())

For API key authentication as an alternative to Bearer tokens, see API Keys.

How API Keys Work

Key Format

All API keys share a recognizable format:

Full key example: kk-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2

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:

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.

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.
• Never store tokens in local storage. Use secure, HTTP-only cookies or in-memory storage to protect tokens from XSS attacks.
• Refresh proactively. Refresh the access token before it expires to avoid request failures. Use the expires_in field to schedule refreshes.
• Handle token rotation. Always store the latest refresh_token from each response - the OIDC provider may rotate refresh tokens.
• Always use PKCE. The Authorization Code flow requires PKCE - generate a code_verifier and code_challenge for every authorization request.
• Invalidate tokens on logout. Always call the Logout endpoint to revoke refresh tokens when a user signs out.
• Protect credentials in transit. All authentication requests must be made over HTTPS.
• Prefer authorization code flow. When possible, use the Exchange Authorization Code flow instead of direct login to avoid handling user passwords.