Skip to main content

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.

React Native
// 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:

OptionRequiredDescription
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 mobile client does not follow. For self-hosted or Sovereign deployments supply your own host.
projectSlugYesThe slug of your Gate project (slug-only; never the internal proj_ ID).
tokenStoreNoCustom 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.

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

Showing example in React Native

The AuthResult object:

FieldTypeDescription
userEndUser{ id, email, displayName } — the authenticated end-user's identity. id is eu_<base62>.
sessionSessionContains accessToken, refreshToken, expiresAt.
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 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.

React Native
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:

React Native
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:

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

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

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

Showing example in React Native

GateError codes:

CodeWhen
INVALID_CREDENTIALSWrong email or password on signIn; unknown or revoked refresh token on refreshToken.
UNAUTHENTICATEDNo valid session, or no stored refresh token.
FORBIDDENThe caller lacks permission for the operation.
NETWORKTransport failure.
DECODINGThe response could not be parsed.
UNKNOWNAny 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-native in the same app.
  • SDK catalogue — all twelve v2-launch SDK languages.