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(...), 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.

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