React Native SDK
@k9o/gate-react-native is the Mobile Gate SDK for React Native. It covers the Gate (Identity-Aware Kernel) authentication surface — signIn, refreshToken, and signOut — for your end-users on iOS and Android.
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/core or one of the other server SDKs. For client-side BYOK/HYOK the Kibo ZK React Native sibling (@k9o/kibo-react-native) pairs with this SDK.
Runtime requirements: React Native 0.74+ on the New Architecture (TurboModules and JSI bindings). Works on bare React Native and Expo with a custom dev client — the managed Expo runtime does not support native modules. Access and refresh tokens persist through the native bridge to Keychain on iOS and EncryptedSharedPreferences on Android.
Installation
npm install @k9o/gate-react-native react-native-keychain
# or
yarn add @k9o/gate-react-native react-native-keychain
For Expo projects, regenerate the native iOS / Android directories after install:
npx expo prebuild
iOS: run pod install in the ios/ directory after adding the package.
Android: no additional steps; the TurboModule auto-links.
Minimum platform versions: iOS 16+ / Android API 24+ (enforced by the native Keychain / Keystore adapters).
Setup
Construct the Gate client once — typically in a module-level singleton or a React context — and import it wherever you need authentication.
// gate.ts
import { GateClient } from '@k9o/gate-react-native'
// Construct once and export; share via Context or a DI layer.
export const gate = new GateClient({
orgBaseUrl: 'https://acme.api-de01.k9o.io', // your organisation's regional address
projectSlug: 'member-portal',
// tokenStore is optional — defaults to KeychainTokenStore (react-native-keychain).
})Showing example in React Native
Constructor options:
| Option | 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 mobile client does not follow. For self-hosted or Sovereign deployments supply your own host. |
projectSlug | Yes | The slug of your Gate project (slug-only; never the internal proj_ ID). |
tokenStore | No | Custom token-persistence adapter. Defaults to the native Keychain (iOS) / EncryptedSharedPreferences (Android) bridge built into the package. |
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 bundle. The server-side apiKey belongs in your backend only.
Custom token store
The store holds one refresh token. The default store is strongly recommended. Supply a custom TokenStore if you need to integrate with an existing secure storage layer or write tests without native modules:
import { GateClient, TokenStore } from '@k9o/gate-react-native'
import * as SecureStore from 'expo-secure-store'
const expoStore: TokenStore = {
save: (token) => SecureStore.setItemAsync('k9o_refresh_token', token),
load: () => SecureStore.getItemAsync('k9o_refresh_token'),
delete: () => SecureStore.deleteItemAsync('k9o_refresh_token'),
}
export const gate = new GateClient({
orgBaseUrl: 'https://acme.api-de01.k9o.io',
projectSlug: 'member-portal',
tokenStore: expoStore,
})
Authenticating the end-user
Sign in
signIn authenticates a registered end-user with email and password. On success it returns an AuthResult containing the end-user identity and session tokens, and persists the access and refresh tokens to the token store automatically.
import { gate } from './gate'
import { GateError } from '@k9o/gate-react-native'
async function handleSignIn(email: string, password: string) {
try {
const result = await gate.signIn({ email, password })
// result.user.id — "eu_<base62>" end-user identifier
// result.session.accessToken — short-lived JWT (Bearer)
// result.session.refreshToken — long-lived refresh token
console.log('Signed in:', result.user.id)
} catch (e) {
if (e instanceof GateError && e.code === 'INVALID_CREDENTIALS') {
showError('Invalid email or password.')
} else {
throw e
}
}
}Signed in: eu_8f3kQ2mZShowing example in React Native
The AuthResult object:
| Field | Type | Description |
|---|---|---|
user | EndUser | { id, email, displayName } — the authenticated end-user's identity. id is eu_<base62>. |
session | Session | Contains accessToken, refreshToken, expiresAt. |
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 timestamp of the access token. |
Sign out
signOut revokes the stored refresh token server-side and clears the persisted tokens from the native store. It resolves to void.
async function handleSignOut() {
try {
await gate.signOut()
navigation.navigate('Login')
} catch (e) {
// Tokens are cleared from the native store regardless.
navigation.navigate('Login')
}
}Showing example in React Native
Social and passwordless sign-in
OAuth2 / OIDC social providers and passwordless (magic-link / OTP) flows are not yet available on the mobile Gate SDK. To use these flows today, see the TypeScript SDK (server-side) or the full 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:
async function fetchProfile(token: string) {
// token is the accessToken from signIn / refreshToken
const response = await fetch(
'https://your-backend.example.com/profile',
{
headers: {
Authorization: `Bearer ${token}`,
},
}
)
const body = await response.json()
// ...
}Showing example in React Native
Refreshing the token
Call refreshToken to exchange the stored refresh token for a new access token before the current one expires:
async function ensureFreshToken() {
try {
const result = await gate.refreshToken()
console.log('New access token expires:', result.expiresAt) // result.accessToken, result.expiresAt
return result
} catch (e) {
if (e instanceof GateError) {
// e.g. UNAUTHENTICATED when no refresh token is stored. Force re-authentication.
navigation.navigate('Login')
} else {
throw e
}
}
}New access token expires: 2026-10-27T11:15:00ZShowing example in React Native
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 native store. 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. Check its code to handle specific cases:
import { GateError } from '@k9o/gate-react-native'
async function doSignIn(email: string, password: string) {
try {
const result = await gate.signIn({ email, password })
console.log('Signed in:', result.user.id)
} catch (e) {
if (e instanceof GateError) {
switch (e.code) {
case 'INVALID_CREDENTIALS':
showError('Invalid email or password.')
break
case 'UNAUTHENTICATED':
navigation.navigate('Login')
break
default:
console.warn(e.code, e.message)
throw e
}
} else {
throw e
}
}
}Signed in: eu_8f3kQ2mZShowing example in React Native
GateError codes:
| Code | When |
|---|---|
INVALID_CREDENTIALS | Wrong email or password on signIn; unknown or revoked refresh token on refreshToken. |
UNAUTHENTICATED | No valid session, or no stored refresh token. |
FORBIDDEN | The caller lacks permission for the operation. |
NETWORK | Transport failure. |
DECODING | The response could not be parsed. |
UNKNOWN | Any other non-2xx status; statusCode and body are set. |
See also
- Gate overview — the Identity-Aware Kernel and both consumption paths (SDK + Gate Studio visual builder).
- TypeScript SDK — server-side SDK with the full auth surface including social/OIDC, passwordless, account lifecycle, and session management.
- API → Auth — the full auth surface: token shapes, social/OIDC/SAML flows, MFA, account lifecycle, session management.
- Kibo — the ZK React Native sibling (
@k9o/kibo-react-native) for client-side BYOK/HYOK; pairs with@k9o/gate-react-nativein the same app. - SDK catalogue — all twelve v2-launch SDK languages.