> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polygon.technology/llms.txt
> Use this file to discover all available pages before exploring further.

# React Native SDK Authentication

> Authenticate users and resolve wallets with the React Native OMS Wallet SDK.

The React Native SDK supports email OTP, OIDC ID-token auth, and low-level OIDC redirect auth. After auth completes, the SDK can automatically select the first existing wallet of the requested type or create one when needed. Use manual wallet selection when your app should present wallet choices.

## Configure

Configure the SDK before using authentication, wallet, signing, transaction, balance, or access APIs.

```typescript theme={null}
import { configure } from '@0xsequence/oms-react-native-sdk'

await configure({
  publishableKey: 'YOUR_PUBLISHABLE_KEY',
  projectId: 'YOUR_PROJECT_ID',
})
```

**Parameters**

| Parameter        | Type                                | Description                                                                 |
| ---------------- | ----------------------------------- | --------------------------------------------------------------------------- |
| `publishableKey` | `string`                            | OMS publishable key sent to the native SDKs.                                |
| `projectId`      | `string`                            | OMS project ID used for request signing scope and session storage scope.    |
| `environment`    | `OmsClientEnvironment` or undefined | Optional override for `walletApiUrl`, `apiRpcUrl`, or `indexerUrlTemplate`. |

**Returns**

Returns `Promise<void>`.

## Start Email Auth

Send a one-time code to the user's email address.

```typescript theme={null}
import { startEmailAuth } from '@0xsequence/oms-react-native-sdk'

await startEmailAuth('user@example.com')
```

**Parameters**

| Parameter | Type     | Description                                    |
| --------- | -------- | ---------------------------------------------- |
| `email`   | `string` | Email address that receives the one-time code. |

**Returns**

Returns `Promise<void>`.

## Complete Email Auth

Complete the flow with the code entered by the user. Automatic mode selects the first matching wallet or creates one when none exists.

```typescript theme={null}
import { completeEmailAuth } from '@0xsequence/oms-react-native-sdk'

const result = await completeEmailAuth({ code: '123456' })

if (result.type === 'walletSelected') {
  console.log('Wallet address:', result.walletAddress)
  console.log('Wallet ID:', result.wallet.id)
}
```

Use manual wallet selection when the app needs to choose between wallets before activating one.

```typescript theme={null}
const result = await completeEmailAuth({
  code: '123456',
  walletSelection: 'manual',
  walletType: 'ethereum',
})

if (result.type === 'walletSelection') {
  await result.pendingSelection.createAndSelectWallet('main')
}
```

**Parameters**

| Parameter         | Type                        | Description                                                                      |
| ----------------- | --------------------------- | -------------------------------------------------------------------------------- |
| `code`            | `string`                    | One-time code entered by the user.                                               |
| `walletSelection` | `'automatic'` or `'manual'` | Defaults to `'automatic'`. Use `'manual'` to receive a pending wallet selection. |
| `walletType`      | `'ethereum'` or undefined   | Optional wallet type. Defaults to `ethereum`.                                    |

**Returns**

Returns `Promise<OmsCompleteAuthResult>`.

| Field              | Type                                      | Description                                                              |
| ------------------ | ----------------------------------------- | ------------------------------------------------------------------------ |
| `type`             | `'walletSelected'` or `'walletSelection'` | Indicates whether a wallet was activated or manual selection is pending. |
| `walletAddress`    | `string` or `null`                        | Active embedded wallet address in automatic mode.                        |
| `wallet`           | `OmsWallet` or `null`                     | Selected or created wallet in automatic mode.                            |
| `wallets`          | `OmsWallet[]`                             | Wallets returned by auth completion.                                     |
| `credential`       | `OmsCredentialInfo`                       | Credential added by auth completion.                                     |
| `pendingSelection` | `OmsPendingWalletSelection` or undefined  | Manual wallet selection helper.                                          |

## Sign In With OIDC ID Token

Authenticate with an ID token your app receives from an OIDC provider.

```typescript theme={null}
import { signInWithOidcIdToken } from '@0xsequence/oms-react-native-sdk'

const result = await signInWithOidcIdToken({
  idToken: 'OIDC_ID_TOKEN',
  issuer: 'https://accounts.google.com',
  audience: 'YOUR_WEB_CLIENT_ID',
  walletSelection: 'automatic',
  walletType: 'ethereum',
})

if (result.type === 'walletSelected') {
  console.log('Wallet address:', result.walletAddress)
}
```

**Parameters**

| Parameter         | Type                        | Description                                                                      |
| ----------------- | --------------------------- | -------------------------------------------------------------------------------- |
| `idToken`         | `string`                    | OIDC ID token issued to the app.                                                 |
| `issuer`          | `string`                    | Expected token issuer.                                                           |
| `audience`        | `string`                    | Expected token audience, such as the app's OIDC client ID.                       |
| `walletSelection` | `'automatic'` or `'manual'` | Defaults to `'automatic'`. Use `'manual'` to receive a pending wallet selection. |
| `walletType`      | `'ethereum'` or undefined   | Optional wallet type. Defaults to `ethereum`.                                    |

**Returns**

Returns `Promise<OmsCompleteAuthResult>`.

## OIDC Provider Config

Use `OidcProviders.google` to build the provider config for Google redirect auth.

```typescript theme={null}
import { OidcProviders } from '@0xsequence/oms-react-native-sdk'

const provider = OidcProviders.google({
  clientId: 'YOUR_WEB_CLIENT_ID',
  relayRedirectUri: null,
})
```

**Parameters**

| Parameter          | Type                                  | Description                                                                                                           |
| ------------------ | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `clientId`         | `string` or undefined                 | Google OAuth client ID. Defaults to the SDK's configured Google client ID.                                            |
| `relayRedirectUri` | `string`, `null`, or undefined        | Relay callback URL. Omit it to use the provider default, or pass `null` to redirect directly to the app redirect URI. |
| `scopes`           | `string[]` or undefined               | OAuth scopes. Defaults to `openid`, `email`, and `profile`.                                                           |
| `authorizeParams`  | `Record<string, string>` or undefined | Extra authorization query parameters.                                                                                 |

**Returns**

Returns `OidcProviderConfig`.

## Start OIDC Redirect Auth

Start an OIDC authorization-code PKCE flow. Apps own browser opening and deep-link handling. Use system auth browser UI such as Custom Tabs or ASWebAuthenticationSession, then pass the resulting app-link URL to `handleOidcRedirectCallback`.

```typescript theme={null}
import {
  OidcProviders,
  startOidcRedirectAuth,
} from '@0xsequence/oms-react-native-sdk'

const started = await startOidcRedirectAuth({
  provider: OidcProviders.google({ clientId: 'YOUR_WEB_CLIENT_ID' }),
  redirectUri: 'com.example.app:/oauth/callback',
  walletType: 'ethereum',
})

console.log('Open this URL with system auth UI:', started.authorizationUrl)
```

**Parameters**

| Parameter          | Type                               | Description                                           |
| ------------------ | ---------------------------------- | ----------------------------------------------------- |
| `provider`         | `OidcProviderConfig`               | OIDC provider config.                                 |
| `redirectUri`      | `string`                           | App callback URL that receives the provider redirect. |
| `walletType`       | `'ethereum'` or undefined          | Optional wallet type. Defaults to `ethereum`.         |
| `relayRedirectUri` | `string`, `null`, or undefined     | Overrides the provider relay redirect URI.            |
| `authorizeParams`  | `Record<string, string>` or `null` | Extra authorization query parameters.                 |

**Returns**

Returns `Promise<OmsStartOidcRedirectAuthResult>`.

| Field              | Type     | Description                                             |
| ------------------ | -------- | ------------------------------------------------------- |
| `authorizationUrl` | `string` | Provider authorization URL to open with system auth UI. |
| `state`            | `string` | OIDC state value stored for callback validation.        |
| `challenge`        | `string` | Wallet auth challenge used in the OIDC request.         |

## Handle OIDC Redirect Callback

Complete redirect auth after the provider sends the user back to your app.

```typescript theme={null}
import { handleOidcRedirectCallback } from '@0xsequence/oms-react-native-sdk'

const result = await handleOidcRedirectCallback({
  callbackUrl: 'com.example.app:/oauth/callback?code=CODE&state=STATE',
  walletSelection: 'manual',
})

if (result.type === 'walletSelection') {
  await result.pendingSelection.createAndSelectWallet('main')
}
```

**Parameters**

| Parameter         | Type                           | Description                                                                      |
| ----------------- | ------------------------------ | -------------------------------------------------------------------------------- |
| `callbackUrl`     | `string`, `null`, or undefined | Full callback URL containing OIDC `code` and `state`.                            |
| `walletSelection` | `'automatic'` or `'manual'`    | Defaults to `'automatic'`. Use `'manual'` to receive a pending wallet selection. |

**Returns**

Returns `Promise<OmsOidcRedirectAuthResult>`.

| Result `type`             | Description                                             |
| ------------------------- | ------------------------------------------------------- |
| `completed`               | Redirect auth completed and returned an active wallet.  |
| `walletSelection`         | Auth completed and manual wallet selection is pending.  |
| `notOidcRedirectCallback` | The URL was not an OIDC redirect callback for this SDK. |
| `noPendingAuth`           | There is no pending redirect auth flow to complete.     |
| `failed`                  | Redirect auth failed and includes a `message`.          |

## List Wallets

List wallets available to the authenticated credential.

```typescript theme={null}
import { listWallets } from '@0xsequence/oms-react-native-sdk'

const wallets = await listWallets()

for (const wallet of wallets) {
  console.log(wallet.id, wallet.type, wallet.address)
}
```

**Parameters**

Takes no parameters.

**Returns**

Returns `Promise<OmsWallet[]>`.

## Use Wallet

Activate an existing wallet by server-side wallet ID.

```typescript theme={null}
import { useWallet } from '@0xsequence/oms-react-native-sdk'

const result = await useWallet('wallet-id')

console.log('Wallet address:', result.walletAddress)
```

**Parameters**

| Parameter  | Type     | Description                                             |
| ---------- | -------- | ------------------------------------------------------- |
| `walletId` | `string` | Wallet ID returned by auth completion or `listWallets`. |

**Returns**

Returns `Promise<OmsWalletActivationResult>`.

## Create Wallet

Create and activate a new wallet for the authenticated user.

```typescript theme={null}
import { createWallet } from '@0xsequence/oms-react-native-sdk'

const result = await createWallet({
  walletType: 'ethereum',
  reference: 'main',
})

console.log('New wallet:', result.walletAddress)
```

**Parameters**

| Parameter    | Type                           | Description                                    |
| ------------ | ------------------------------ | ---------------------------------------------- |
| `walletType` | `'ethereum'` or undefined      | Wallet type to create. Defaults to `ethereum`. |
| `reference`  | `string`, `null`, or undefined | Optional app-defined wallet reference.         |

**Returns**

Returns `Promise<OmsWalletActivationResult>`.