Sessions

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:

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.

Get the current token

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

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

A session has two tokens with different lifetimes. The access token lives 15 minutes and authenticates every request. The refresh token lives 30 days and rotates on each use — so a session stays alive indefinitely with regular activity, and ends after 30 days of inactivity.

You never handle this yourself: the SDK refreshes the access token automatically about a minute before expiry (deduplicated across concurrent calls), including before function invocations. Your code only sees the terminal case — when the refresh token itself has expired or been revoked, currentUser() returns null and the stored tokens are cleared.

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