OfflineID SDK for React Native

Use @offline-protocol/id-react-native@0.3.3 for hosted email sign-in, profiles and connections in a React Native or Expo app. Create an application in the developer portal. The appId prop is the application’s public identifier, not a secret key.

Prerequisites

Node.js 18.x or higher
React 18.x or 19.x
React Native or Expo
A package manager: npm or yarn

Install

Install the SDK and its peer dependencies:

npx expo install @offline-protocol/id-react-native@0.3.3 @offline-protocol/core @react-native-async-storage/async-storage@^2.2.0 react-native-svg axios

For a bare React Native application:

npm install @offline-protocol/id-react-native@0.3.3 @offline-protocol/core @react-native-async-storage/async-storage@^2.2.0 react-native-svg axios
npx pod-install

Version 0.3.3 declares a peer dependency on @react-native-async-storage/async-storage ^2.2.0. Without the version, the package manager installs async-storage 3.x, which is outside that range.

Add the provider

Pass your App ID (app_...) as appId. The prop is optional in the published types, but hosted requests fail without it: the provider logs a warning and API calls throw App ID not set. The provider initializes the SDK, restores any saved session on launch, and makes auth state available to hooks throughout your app.

Expo Router

import { Stack } from "expo-router";
import { OfflineAppProvider } from "@offline-protocol/id-react-native";

const APP_ID = "app_your_application_id";

export default function RootLayout() {
  return (
    <OfflineAppProvider appId={APP_ID}>
      <Stack />
    </OfflineAppProvider>
  );
}

React Native (App entry)

import { OfflineAppProvider } from "@offline-protocol/id-react-native";
import App from "./App";

const APP_ID = "app_your_application_id";

export default function Root() {
  return (
    <OfflineAppProvider appId={APP_ID}>
      <App />
    </OfflineAppProvider>
  );
}

Verify your setup

Use the useAuth hook to read auth state. On launch, the SDK asynchronously restores a session from the stored token; check loading before treating user === null as logged out.

import { Text } from "react-native";
import { useAuth } from "@offline-protocol/id-react-native";

function TestComponent() {
  const { user, loading, sessionRestoreError } = useAuth();

  if (loading) {
    return <Text>Loading session…</Text>;
  }

  if (sessionRestoreError?.reason === "network") {
    return <Text>No connection. Your session will restore when connected.</Text>;
  }

  return (
    <Text>
      SDK connected! User: {user?.email ?? "Not authenticated"}
    </Text>
  );
}

Session restore errors

When a stored token cannot be validated, sessionRestoreError is set with a typed reason:

Reason	Meaning	SDK behavior
`"network"`	DNS failure, timeout, or device offline	Token is kept; retry when online
`"unauthorized"`	Token expired or invalid (401/403)	Token is cleared
`"unknown"`	Server error or unexpected response	Token is kept

Call loginWithModal() to open the built-in login bottom sheet. It returns void; the modal handles email OTP verification and username registration internally.

import { TouchableOpacity, Text } from "react-native";
import { useAuth } from "@offline-protocol/id-react-native";

function LoginButton() {
  const { loginWithModal, user, logout } = useAuth();

  if (user) {
    return (
      <>
        <Text>Welcome, {user.email}!</Text>
        <TouchableOpacity onPress={logout}>
          <Text>Log out</Text>
        </TouchableOpacity>
      </>
    );
  }

  return (
    <TouchableOpacity onPress={loginWithModal}>
      <Text>Log in with OfflineID</Text>
    </TouchableOpacity>
  );
}

export default LoginButton;

API reference

`OfflineAppProvider`

Prop	Type	Required	Description
`appId`	`string`	No	App ID from the developer portal. Optional in the types; hosted requests fail without it.
`children`	`ReactNode`	Yes	App content

`useAuth()`

Field	Type	Description
`user`	`UserAccount \| null`	Current authenticated user
`token`	`string \| null`	Bearer token for API requests
`loading`	`boolean`	`true` while session restore is in progress
`sessionRestoreError`	`SessionRestoreFailedError \| null`	Set when session restore fails
`loginWithModal`	`() => void`	Opens the built-in login bottom sheet
`logout`	`() => void`	Clears user, token, and stored auth token
`sendCode`	`(email: string) => Promise<boolean>`	Sends OTP to email
`verifyCode`	`(email: string, otp: string) => Promise<UserAccount \| null>`	Verifies OTP and signs in
`refreshUser`	`() => Promise<void>`	Re-fetches the current user from `/users/me`
`registerUsername`	`(username: string) => Promise<Profile \| null>`	Registers a username for the current user
`isUsernameAvailable`	`(username: string) => Promise<boolean>`	Checks username availability

Other hooks

import {
  useProfiles,
  useConnections,
} from "@offline-protocol/id-react-native";

Hook	Purpose
`useProfiles()`	List, search, and count user profiles
`useConnections()`	Manage peer connections

Signed OfflineID credential

Version 0.3.3 exports useOfflineIdCredential, fetchOfflineIdCredential and fetchOfflineIdIssuerKey. These obtain an issuer-signed binding between an account, username and off1 address. The account must have a bound identity address before issuance. See credential issuance and issuer key. Verify the signature, issuer key, address, expiry and intended account before accepting the credential. A cached credential permits offline signature verification; it does not establish current account status or replace application authorization. Issuance returns 503 when not enabled, and 409 when the account has no bound address. The package also exports setAppId, fetchSessionFromToken and isSessionRestoreFailedError for integrations that manage session restoration directly. The built-in session provider stores its JWT unencrypted in AsyncStorage. Applications requiring platform secure storage must manage token storage and restoration explicitly; use fetchSessionFromToken to restore a session from an externally stored token. React 0.2.0 on the web has no credential hook. Version 0.3.3 sends x-app-id. Sign-ins are attributed to the application for analytics, app membership and usage-limit enforcement. The projectId prop and setProjectId remain deprecated aliases; use appId and setAppId in new integrations. Version 0.3.3 no longer exports useProofOfLocation or accepts locationProvider. Use the standalone @offline-protocol/pol package (0.1.2 on npm), which completes the witness exchange; see Submit a location claim.

OfflineID SDK

API documentation

Authentication

Users

Profiles

Connections

Network

OfflineID SDK for React Native

Prerequisites

Install

Add the provider

Expo Router

React Native (App entry)

Verify your setup

Session restore errors

API reference

`OfflineAppProvider`

`useAuth()`

Other hooks

Signed OfflineID credential

​Prerequisites

​Install

​Add the provider

​Expo Router

​React Native (App entry)

​Verify your setup

​Session restore errors

​Sign in users

​API reference

​OfflineAppProvider

​useAuth()

​Other hooks

​Signed OfflineID credential

Prerequisites

Install

Add the provider

Expo Router

React Native (App entry)

Verify your setup

Session restore errors

Sign in users

API reference

`OfflineAppProvider`

`useAuth()`

Other hooks

Signed OfflineID credential