Skip to main content

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.

Flutter
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:

FieldRequiredDescription
orgBaseUrlYesYour 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.
projectSlugYesThe slug of your Gate project (slug-only; never the internal proj_ ID).
tokenStoreNoWhere 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 localStorage with 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.

Flutter
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.');
}
}
Output · bash
Signed in: eu_8f3kQ2mZ

Showing example in Flutter

The AuthResult object:

FieldTypeDescription
userEndUser{ id, email, displayName } — the authenticated end-user. id is the eu_<base62> identifier.
session.accessTokenStringSigned 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.refreshTokenStringOpaque refresh token; replaced on every refresh.
session.expiresAtStringISO 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).

Flutter
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:

Flutter
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:

Flutter
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');
}
}
Output · bash
New access token expires: 2026-10-27T11:15:00Z

Showing 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:

Flutter
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.
}
}
Output · bash
Signed in: eu_8f3kQ2mZ

Showing example in Flutter

GateError cases:

CaseWhen
GateError.invalidCredentialsWrong email or password on signIn; unknown or revoked refresh token on refreshToken.
GateError.unauthenticatedNo valid session, or no stored refresh token.
GateError.forbiddenThe caller lacks permission for the operation.
GateError.networkTransport failure: network unreachable, timeout.
GateError.decodingThe response could not be parsed.
GateError.unknownAny 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_gate in the same Flutter app.
  • SDK catalogue — all twelve v2-launch SDK languages.