Authentication

KalamDB supports username/password login and JWT bearer tokens. For long-lived apps, prefer JWT + refresh. Server install and first-user creation are in the server quick start, not in this SDK.

Auth types

1import 'package:kalam_link/kalam_link.dart';2 3Auth.basic('user', 'password');     // Username/password login4Auth.jwt('eyJhbGci...');            // JWT bearer token5Auth.none();                         // No auth (localhost bypass)

authProvider — recommended

Use authProvider as the source of credentials. The callback is invoked when the client is created, and you can re-run it with refreshAuth() when your token changes or before an explicit reconnect path:

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

The AuthProvider typedef is:

1typedef AuthProvider = Future<Auth> Function();

Provider return guidance

Return Auth.jwt(...) for normal deployments.

The Dart SDK also supports:

• Auth.basic(...) when you want the client to exchange user/password credentials for a JWT on POST /v1/api/auth/login before the first query or WebSocket connect
• Auth.none() for local anonymous access

There is no separate auth: parameter on KalamClient.connect(...) in the Dart SDK. Auth flows go through authProvider, login(...), exchangeOidcToken(...), and refreshToken(...).

refreshAuth()

Call refreshAuth() to proactively push fresh credentials to the Rust layer without waiting for the next reconnect — useful for scheduled token rotation:

1// Refresh tokens every 55 minutes2Timer.periodic(const Duration(minutes: 55), (_) => client.refreshAuth());

refreshAuth() re-runs the configured authProvider and pushes the refreshed credentials into the Rust client.

Login (user/password → JWT upgrade)

If your server requires an explicit login step, create a temporary client, perform login(), then reconnect with the returned access token:

1final bootstrap = await KalamClient.connect(2  url: 'https://db.example.com',3  authProvider: () async => Auth.none(),4);5 6final session = await bootstrap.login('alice', 'Secret123!');7await bootstrap.dispose();8 9final client = await KalamClient.connect(10  url: 'https://db.example.com',11  authProvider: () async => Auth.jwt(session.accessToken),12);

If you return Auth.basic(...) from authProvider, the SDK will also perform the login exchange automatically before the first query or WebSocket connection.

OIDC / Keycloak

KalamDB accepts any configured OIDC issuer (Keycloak, Dex, Okta, and others). The Dart SDK does not open a browser. Obtain an ID token in the Flutter app, then exchange it:

1final session = await client.exchangeOidcToken(idToken);2print(session.accessToken);

This calls POST /v1/api/auth/oidc/exchange-token and stores the returned KalamDB JWT on the client. You can also return Auth.jwt(idToken) from authProvider when the server trusts the IdP as a bearer issuer (auth.jwt_trusted_issuers). Prefer exchangeOidcToken when you want KalamDB-issued access and refresh tokens.

See Keycloak and OIDC configuration.

Refresh token

If you have a refresh token and want a new access token:

1final fresh = await client.refreshToken(refreshToken);2print('new access token: ${fresh.accessToken}');