Flutter SDK
k9o_gate is the Mobile Gate SDK for Flutter. It covers the Gate (Identity-Aware Kernel) authentication surface — signIn, refreshToken, and signOut — for your end-users on iOS, Android, web, macOS, Linux, and Windows.
This is an auth-only library. It has no data-plane (from(), select(), encryption, functions). For full platform access your server-side code uses k9o from pub.dev or one of the eight server SDKs. For client-side BYOK/HYOK the Kibo ZK Dart sibling pairs with this SDK.
Runtime requirements: Dart 3.3+ and Flutter 3.22+. Covers iOS 16+, Android API 24+, web, macOS, Linux, and Windows. Async Dart throughout.
Installation
# pubspec.yaml
dependencies:
k9o_gate: ^1.5.0
Or add via the CLI:
flutter pub add k9o_gate
flutter_secure_storage is the default token store — bundled as a transitive dependency of k9o_gate. Keychain on iOS, Keystore-backed EncryptedSharedPreferences on Android, and the platform Credential Manager on web. You can supply your own implementation; the default is recommended.
Minimum platform config. On Android set minSdkVersion 24 in android/app/build.gradle. No additional entitlements are required on iOS or macOS; flutter_secure_storage uses the default Keychain access group.
Setup
Construct the Gate client once — typically at app startup or inside a provider — and make it available to your widget tree.
import 'package:k9o_gate/k9o_gate.dart';
// Construct once, share via Provider / Riverpod / GetIt / etc.
final gate = GateClient(
orgBaseUrl: 'https://acme.api-de01.k9o.io', // your organisation's regional address
projectSlug: 'member-portal',
// tokenStore defaults to SecureTokenStore (flutter_secure_storage)
);Showing example in Flutter
Constructor fields:
| Field | Required | Description |
|---|---|---|
orgBaseUrl | Yes | Your organisation's regional API address, for example https://acme.api-de01.k9o.io. Use the regional address, not the region-free one: the region-free address only answers with a redirect, which the Dart client does not follow. For self-hosted or Sovereign deployments supply your own host instead. |
projectSlug | Yes | The slug of your Gate project (slug-only; never the internal proj_ ID). |
tokenStore | No | Where the SDK persists the access and refresh tokens between app restarts. Defaults to SecureTokenStore (backed by flutter_secure_storage) if omitted. |
No API key. The mobile Gate client is unauthenticated until an end-user calls signIn. There is no server-side API key and none should be embedded in a mobile app — doing so would expose a privileged credential to anyone who can inspect the binary. The server-side apiKey belongs in your backend only.
Token store and secure storage
tokenStore is the persistence layer for the session returned by signIn. The default SecureTokenStore wraps flutter_secure_storage, which maps to:
- iOS / macOS — Keychain Services
- Android —
EncryptedSharedPreferences(Keystore-backed AES-256) - Web — platform Credential Manager or
localStoragewith encryption
The store holds one refresh token. You can supply a custom TokenStore implementation (e.g. for testing or to integrate with an existing secure storage layer):
class MyTokenStore implements TokenStore {
@override
Future<void> save(String token) async { /* ... */ }
@override
Future<String?> load() async { /* ... */ }
@override
Future<void> delete() async { /* ... */ }
}
final gate = GateClient(
orgBaseUrl: 'https://acme.api-de01.k9o.io',
projectSlug: 'member-portal',
tokenStore: MyTokenStore(),
);
Authenticating the end-user
Sign in
signIn authenticates a registered end-user with email and password. On success it returns an AuthResult and persists the access and refresh tokens to tokenStore automatically.
import 'package:k9o_gate/k9o_gate.dart';
Future<void> handleSignIn(String email, String password) async {
try {
final result = await gate.signIn(
email: email,
password: password,
);
// result.user.id — "eu_<base62>" end-user identifier
// result.session.accessToken — short-lived JWT (Bearer)
// result.session.refreshToken — long-lived rotation token
print('Signed in: ${result.user.id}');
} on GateError catch (error) {
print(error); // GateError.invalidCredentials: Invalid credentials.
showError('Invalid email or password.');
}
}Signed in: eu_8f3kQ2mZShowing example in Flutter
The AuthResult object:
| Field | Type | Description |
|---|---|---|
user | EndUser | { id, email, displayName } — the authenticated end-user. id is the eu_<base62> identifier. |
session.accessToken | String | Signed JWT; attach as Authorization: Bearer <token> on requests to your backend or directly to the Gate API. TTL: 1 hour by default (project-configurable). |
session.refreshToken | String | Opaque refresh token; replaced on every refresh. |
session.expiresAt | String | ISO 8601 expiry of the access token. |
Sign out
signOut revokes the stored refresh token server-side and clears the persisted tokens from tokenStore. It returns a Future<bool> (true when a live session was revoked).
Future<void> handleSignOut() async {
try {
await gate.signOut();
navigateTo('/login');
} on GateError catch (e) {
// Tokens are cleared from tokenStore regardless; navigate to login.
navigateTo('/login');
}
}Showing example in Flutter
SSO, social, and passwordless flows (OAuth2/OIDC, magic-link, OTP) are not yet available on the mobile SDK. For the full auth surface — token shapes, social/OIDC/SAML, MFA, account lifecycle — see the TypeScript SDK or the Auth API reference.
Using the session
Attaching the session to requests
Keep the accessToken that signIn or refreshToken returns, and pass it as a Bearer header on every authenticated call to your backend:
import 'package:http/http.dart' as http;
Future<void> fetchProfile(String token) async {
// token is the accessToken from signIn / refreshToken
final response = await http.get(
Uri.parse('https://your-backend.example.com/profile'),
headers: {
'Authorization': 'Bearer $token',
},
);
// ...
}Showing example in Flutter
Refreshing the token
Call refreshToken to exchange the stored refresh token for a new access token before the current one expires:
Future<void> ensureFreshToken() async {
try {
final result = await gate.refreshToken();
print('New access token expires: ${result.expiresAt}'); // result.accessToken, result.expiresAt
} on GateError catch (error) {
// e.g. GateError.unauthenticated when no refresh token is stored.
// Force re-authentication.
navigateTo('/login');
}
}New access token expires: 2026-10-27T11:15:00ZShowing example in Flutter
refreshToken returns accessToken, refreshToken and expiresAt. Each refresh returns a new refresh token and the one you sent stops working; the SDK keeps the new one in the tokenStore. Sending an old refresh token again ends the session. revokeAllSessions ends every session of the signed-in user, this device included. See Session lifetime and sign-out.
Error handling
All Gate methods throw GateError on failure. It has six cases:
import 'package:k9o_gate/k9o_gate.dart';
Future<void> doSignIn(String email, String password) async {
try {
final result = await gate.signIn(email: email, password: password);
print('Signed in: ${result.user.id}');
} on GateError catch (error) {
print(error); // GateError.invalidCredentials: Invalid credentials.
}
}Signed in: eu_8f3kQ2mZShowing example in Flutter
GateError cases:
| Case | When |
|---|---|
GateError.invalidCredentials | Wrong email or password on signIn; unknown or revoked refresh token on refreshToken. |
GateError.unauthenticated | No valid session, or no stored refresh token. |
GateError.forbidden | The caller lacks permission for the operation. |
GateError.network | Transport failure: network unreachable, timeout. |
GateError.decoding | The response could not be parsed. |
GateError.unknown | Any other non-2xx status, with statusCode and body. |
See also
- Gate overview — the Identity-Aware Kernel and both consumption paths (SDK + Gate Studio visual builder).
- API → Auth — the full auth surface: token shapes, social/OIDC/SAML flows, MFA, account lifecycle, session management.
- Kibo — the ZK Dart sibling for client-side BYOK/HYOK; pairs with
k9o_gatein the same Flutter app. - SDK catalogue — all twelve v2-launch SDK languages.