Sessions

Koolbase uses JWT-based sessions. Tokens are stored securely on device and automatically included in all SDK requests.

How sessions work

When a user logs in, the server creates a session record in project_sessions and returns a signed JWT. The SDK stores this token using flutter_secure_storage — encrypted on device using the platform keychain (iOS Keychain / Android Keystore).

On subsequent app launches, the SDK loads the stored token and validates it against the server. If valid, the session is restored automatically — no login screen required.

Check session on startup

Check whether a valid session exists before deciding which screen to show:

lib/main.dartDart

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Koolbase.init(apiKey: 'pk_live_...');

  final user = await Koolbase.auth.currentUser();

  runApp(MyApp(initialRoute: user != null ? '/home' : '/login'));
}

Session scoping

Sessions are scoped per project environment. A session token from your production environment cannot be used in staging or development.

Environment isolation

If you switch environments during development, existing stored tokens from the previous environment will fail validation. Call Koolbase.auth.logout() to clear the stored token before switching.

Get the current token

If you need the raw JWT token — for example, to pass to your own backend — you can retrieve it directly:

lib/auth.dartDart

final token = await Koolbase.auth.getToken();
// Use token in your own API requests
final response = await http.get(
  Uri.parse('https://your-api.com/profile'),
  headers: {'Authorization': 'Bearer $token'},
);

Session expiry

Sessions expire after 30 days of inactivity by default. When a session expires, currentUser() returns null and the stored token is cleared automatically.

lib/auth.dartDart

final user = await Koolbase.auth.currentUser();
if (user == null) {
  // Session expired or user never logged in
  // Redirect to login
}