Authentication

KalamDB supports user/password bootstrap and JWT bearer tokens. For long-lived apps, prefer JWT + refresh flows.

Auth types

1import 'package:kalam_link/kalam_link.dart';2 3Auth.basic('user', 'password');     // User/password bootstrap4Auth.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(...), 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.

disableCompression

Disable gzip compression on WebSocket messages for easier local debugging:

1final client = await KalamClient.connect(2  url: 'http://localhost:2900',3  authProvider: () async => Auth.jwt(await getToken()),4  disableCompression: true, // appends ?compress=false to the WS URL5);

The server will respond with plain-text JSON frames instead of compressed binary frames, making inspection in Wireshark or proxy tools straightforward.

Do not use in production. Compression significantly reduces bandwidth. Only enable for local debugging.

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.

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}');