> ## 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 and Google sign-in through OIDC ID-token auth or authorization-code redirect auth. Authentication returns an active wallet by default. Use manual wallet selection when your app should present wallet choices.

## Create The Client

Create `OMSClient` before using authentication, wallet, signing, transaction, balance, or access APIs.

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

const oms = new OMSClient({
  publishableKey: 'YOUR_PUBLISHABLE_KEY',
})
```

**Parameters**

| Parameter        | Type     | Description                                                                         |
| ---------------- | -------- | ----------------------------------------------------------------------------------- |
| `publishableKey` | `string` | Publishable key. The SDK selects the matching OMS Wallet environment from this key. |

**Returns**

Returns an `OMSClient` instance with `wallet`, `indexer`, and `supportedNetworks`.

## Start Email Auth

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

```typescript theme={null}
await oms.wallet.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 returns an active wallet when possible.

```typescript theme={null}
const result = await oms.wallet.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 oms.wallet.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`.                                    |
| `sessionLifetimeSeconds` | `number`, `null`, or undefined | Optional requested wallet API session lifetime in seconds. Defaults to one week. |

**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 OMS 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 a Google ID token.

```typescript theme={null}
const result = await oms.wallet.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`                       | Google ID token issued to the app.                                               |
| `issuer`                 | `string`                       | Expected token issuer, such as `https://accounts.google.com`.                    |
| `audience`               | `string`                       | Expected token audience, such as the app's Google 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`.                                    |
| `sessionLifetimeSeconds` | `number`, `null`, or undefined | Optional requested wallet API session lifetime in seconds. Defaults to one week. |

**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',
})
```

**Parameters**

| Parameter         | Type                                  | Description                                                                |
| ----------------- | ------------------------------------- | -------------------------------------------------------------------------- |
| `clientId`        | `string` or undefined                 | Google OAuth client ID. Defaults to the SDK's configured Google client ID. |
| `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 a Google authorization-code PKCE flow. Apps own browser opening and deep-link handling. Open the authorization URL in the platform system auth browser, then pass the resulting app-link URL to `handleOidcRedirectCallback`.

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

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

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

// When the app receives the callback URL from its deep-link handler:
const result = await oms.wallet.handleOidcRedirectCallback({
  callbackUrl: 'yourapp://oauth/callback?code=CODE&state=STATE',
})
```

**Parameters**

| Parameter         | Type                               | Description                                                                                                     |
| ----------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `provider`        | `OidcProviderConfig`               | Google provider config returned by `OidcProviders.google`.                                                      |
| `redirectUri`     | `string`                           | App callback URL that receives the provider redirect. Configure this URL scheme or app link in your native app. |
| `walletType`      | `'ethereum'` or undefined          | Optional wallet type. Defaults to `ethereum`.                                                                   |
| `authorizeParams` | `Record<string, string>` or `null` | Extra authorization query parameters.                                                                           |
| `loginHint`       | `string`, `null`, or undefined     | Optional Google `login_hint`. When omitted for Google, the SDK can reuse the previous session email.            |

**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}
const result = await oms.wallet.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. |
| `sessionLifetimeSeconds` | `number`, `null`, or undefined | Optional requested wallet API session lifetime in seconds. Defaults to one week. |

**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}
const wallets = await oms.wallet.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}
const result = await oms.wallet.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}
const result = await oms.wallet.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>`.