Configuration

RakomiProvider is the SDK’s single root widget. It mounts the auth controller, the native adapter, and the deep-link handler for the widget subtree beneath child.

RakomiProvider(
  publishableKey: 'pk_live_…',
  redirectUri: 'myapp://callback',
  child: MyApp(),
)

Parameters

Parameter	Type	Required	Default	Notes
publishableKey	String	Yes	—	Identifies your tenant. Also used to derive tenantId when tenantId is not supplied.
redirectUri	String	Yes	—	Callback URI for social/OAuth sign-in. See Installation for platform scheme rules.
child	Widget	Yes	—	The widget subtree that can reach RakomiProvider.of(context).
apiBaseUrl	String?	No	https://api.rakomi.com	The API host. Must be https://, or the dev-loopback exception below.
issuer	String?	No	https://api.rakomi.com	Expected JWT iss. This is the platform brand identifier, not necessarily your apiBaseUrl — a custom-domain tenant still receives tokens issued by the platform issuer.
audience	String?	No	https://api.rakomi.com	Expected JWT aud.
tenantId	String?	No	publishableKey	Explicit tenant id, when it differs from the publishable key.
adapter	RakomiNativeAdapter?	No	DefaultRakomiNativeAdapter()	Swap the native adapter — for testing, or an alternative storage/browser/biometric implementation.
jwksUrl	Uri?	No	$apiBaseUrl/.well-known/jwks.json	Override the JWKS endpoint. Subject to the same https://-or-loopback validation as apiBaseUrl.
refreshLeadtime	Duration	No	kDefaultRefreshLeadtime (60s)	How far ahead of exp the SDK proactively refreshes.
freshAuthWindow	Duration	No	30s	Accepted by the constructor and stored, but not currently wired to any runtime behavior — there is no fresh-auth-window enforcement today, in either direction.
certificateFingerprints	List<String>?	No	null	Optional certificate pinning for https:// requests to non-loopback hosts, on iOS and Android. Ignored on Web (browser TLS). Supply more than one fingerprint (e.g. a backup pin) so a routine certificate rotation does not require an SDK update.

Validation

The constructor validates two URLs synchronously and throws ArgumentError if either fails:

• apiBaseUrl must start with https://, or match a dev-loopback exception: http://localhost, http://127.x.x.x, or http://10.x.x.x (with an optional port/path). The match is anchored to the host, so http://localhost.evil.com does not qualify.
• jwksUrl, when supplied, is validated against the same rule — the signing-key set is the root of signature trust, so an unvalidated http:// JWKS endpoint would fetch keys in plaintext and outside certificate pinning.

Caution

10.0.0.0/8 is a private LAN range, not loopback — traffic to it leaves the device. Treat the dev-loopback exception as a local-development convenience only; never point a production build at a plaintext http:// address.

Resolving the controller

RakomiAuth auth = RakomiProvider.of(context);       // throws if no enclosing provider
RakomiAuth? auth = RakomiProvider.maybeOf(context);  // null if no enclosing provider

RakomiProvider is not a process-global singleton — of/maybeOf resolve to the nearest enclosing RakomiProvider. Multiple providers can coexist in the same widget tree (for example, a multi-tenant test harness), each with its own independent RakomiAuth instance and its own tenant-namespaced storage.

Custom native adapter

Supply your own adapter to swap storage, the system-browser launcher, the biometric gate, or connectivity detection — for example, in tests, or to plug in an alternative platform plugin. RakomiNativeAdapter is @sealed for the 0.x line: its contract is additive-only, and a breaking change to it ships as a minor version bump (0.1.x → 0.2.0) with a migration note, not silently.

See Session & tokens for what the default adapter persists and where, and Security for the full threat model.