Token Auth

Use token auth when your app should send Authorization: Bearer <token> on every request instead of raw username/password credentials.

KalamDB supports two token sources:

• internal JWTs returned by POST /v1/api/auth/login
• external OIDC JWTs from trusted issuers such as Firebase or Keycloak

Internal Token Flow

The built-in login flow is:

1. Send username and password to POST /v1/api/auth/login.
2. Receive access_token and refresh_token.
3. Send the access token on API and WebSocket requests.
4. Refresh it through POST /v1/api/auth/refresh when needed.

Login

curl -X POST http://127.0.0.1:8080/v1/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"AdminPass123!"}'

Typical response fields:

• access_token
• refresh_token
• expires_at or token-expiry metadata
• authenticated user profile fields

Use the access token

TOKEN="<access_token>"
 
curl -X POST http://127.0.0.1:8080/v1/api/sql \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"sql":"SELECT CURRENT_USER();"}'

Refresh Tokens

REFRESH="<refresh_token>"
 
curl -X POST http://127.0.0.1:8080/v1/api/auth/refresh \
  -H "Authorization: Bearer $REFRESH"

Use the returned access token for subsequent requests.

Checking Auth State

There are two practical checks:

Check the current authenticated user

curl http://127.0.0.1:8080/v1/api/auth/me \
  -H "Authorization: Bearer $TOKEN"

This confirms whether the token is accepted and shows the current user record.

Check from SQL

curl -X POST http://127.0.0.1:8080/v1/api/sql \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"sql":"SELECT CURRENT_USER();"}'

This is the fastest way to confirm the runtime identity that SQL sees.

External Provider Tokens

If you already have a JWT from Firebase, Keycloak, or another trusted OIDC issuer, skip the login endpoint and send that token directly as a bearer token.

KalamDB will:

1. read alg and iss
2. reject untrusted issuers
3. perform OIDC discovery for the issuer
4. fetch and cache the issuer JWKS
5. validate the token signature and claims
6. resolve or create the matching local user

Provider setup details live in:

• OIDC & Issuer Trust
• Firebase
• Keycloak

SDK Pattern

For long-lived apps, return a fresh token from the SDK auth provider callback instead of hard-coding a token once.

TypeScript

import { Auth, createClient, type AuthProvider } from 'kalam-link';
 
const authProvider: AuthProvider = async () => {
  const token = await myApp.getOrRefreshJwt();
  return Auth.jwt(token);
};
 
const client = createClient({
  url: 'https://db.example.com',
  authProvider,
});

Dart

final client = await KalamClient.connect(
  url: 'https://db.example.com',
  authProvider: () async {
    final token = await myApp.getOrRefreshJwt();
    return Auth.jwt(token);
  },
);

Configuration Notes

Internal token auth still depends on a strong shared secret:

[authentication]
jwt_secret = "replace-with-strong-random-secret-32-plus-chars"
cookie_secure = true

Use KALAMDB_JWT_SECRET in production instead of committing secrets to server.toml.

Related

• Authentication Overview
• Auto-Provisioning Users
• HTTP API Reference
• Authentication & Bootstrap