> ## 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.

# TypeScript SDK Authentication

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

The TypeScript SDK supports email OTP and Google sign-in through OIDC authorization-code redirect authentication. Authentication returns an active wallet by default. Use manual wallet selection when your app should present wallet choices.

## Start Email Auth

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

```typescript theme={null}
await oms.wallet.startEmailAuth({ email: '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' })

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}
import { WalletType } from '@0xsequence/typescript-sdk'

const selection = await oms.wallet.completeEmailAuth({
  code: '123456',
  walletType: WalletType.Ethereum,
  walletSelection: 'manual',
})

const existingWallet = selection.wallets[0]

if (existingWallet) {
  await selection.selectWallet({ walletId: existingWallet.id })
} else {
  await selection.createAndSelectWallet({ reference: 'main' })
}
```

**Parameters**

| Parameter                | Type                        | Description                                                                      |
| ------------------------ | --------------------------- | -------------------------------------------------------------------------------- |
| `code`                   | `string`                    | One-time code entered by the user.                                               |
| `walletType`             | `WalletType` or undefined   | Optional wallet type. Defaults to `WalletType.Ethereum`.                         |
| `walletSelection`        | `'automatic'` or `'manual'` | Defaults to `'automatic'`. Use `'manual'` to receive a pending wallet selection. |
| `sessionLifetimeSeconds` | `number` or undefined       | Optional requested wallet API session lifetime in seconds. Defaults to one week. |

**Returns**

Returns `Promise<CompleteEmailAuthResult>` in automatic mode, or `Promise<PendingWalletSelection>` in manual mode.

| Field           | Type               | Description                          |
| --------------- | ------------------ | ------------------------------------ |
| `walletAddress` | `Address`          | Active non-custodial wallet address. |
| `wallet`        | `OmsWallet`        | Selected or created wallet.          |
| `wallets`       | `OmsWallet[]`      | Wallets returned by auth completion. |
| `credential`    | `WalletCredential` | Credential added by auth completion. |

Manual mode returns `PendingWalletSelection`.

| Field                   | Type                                                          | Description                                                  |
| ----------------------- | ------------------------------------------------------------- | ------------------------------------------------------------ |
| `walletType`            | `WalletType`                                                  | Wallet type being selected or created.                       |
| `wallets`               | `OmsWallet[]`                                                 | Existing wallets available for the authenticated credential. |
| `credential`            | `WalletCredential`                                            | Credential added by auth completion.                         |
| `selectWallet`          | `({ walletId: string }) => Promise<WalletActivationResult>`   | Activates an existing wallet by wallet ID.                   |
| `createAndSelectWallet` | `({ reference?: string }) => Promise<WalletActivationResult>` | Creates and activates a new wallet.                          |

## Start OIDC Redirect Auth

Start a Google authorization-code PKCE flow.

```typescript theme={null}
const redirect = await oms.wallet.startOidcRedirectAuth({
  provider: 'google',
  redirectUri: `${window.location.origin}/auth/callback`,
})

window.location.assign(redirect.url)
```

**Parameters**

| Parameter         | Type                                  | Description                                                                                                                                                               |
| ----------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `provider`        | Provider name or provider config      | Use `google` for Google redirect auth.                                                                                                                                    |
| `redirectUri`     | `string`                              | App callback URL that receives the provider redirect.                                                                                                                     |
| `walletType`      | `WalletType` or undefined             | Optional wallet type. Defaults to `WalletType.Ethereum`.                                                                                                                  |
| `authorizeParams` | `Record<string, string>` or undefined | Extra authorization query parameters passed to the provider.                                                                                                              |
| `loginHint`       | `string` or undefined                 | Optional Google `login_hint`. When omitted for Google, the SDK can reuse the previous session email before starting redirect auth. Pass an empty string to force no hint. |

**Returns**

Returns `Promise<StartOidcRedirectAuthResult>`.

| Field       | Type     | Description                                                           |
| ----------- | -------- | --------------------------------------------------------------------- |
| `url`       | `string` | Provider authorization URL. Open this URL to continue authentication. |
| `state`     | `string` | SDK-managed OIDC state value.                                         |
| `challenge` | `string` | SDK-managed challenge value.                                          |

## Complete OIDC Redirect Auth

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

```typescript theme={null}
const result = await oms.wallet.completeOidcRedirectAuth({
  callbackUrl: window.location.href,
  cleanUrl: true,
})

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

**Parameters**

| Parameter                | Type                                  | Description                                                                      |
| ------------------------ | ------------------------------------- | -------------------------------------------------------------------------------- |
| `callbackUrl`            | `string`                              | Full callback URL containing the OIDC `code` and `state` query parameters.       |
| `cleanUrl`               | `boolean` or undefined                | Whether to remove OIDC query parameters from the current URL after parsing.      |
| `replaceUrl`             | URL replacement callback or undefined | Custom URL replacement callback for non-browser runtimes or routers.             |
| `walletSelection`        | `'automatic'` or `'manual'`           | Defaults to `'automatic'`. Use `'manual'` to receive a pending wallet selection. |
| `sessionLifetimeSeconds` | `number` or undefined                 | Optional requested wallet API session lifetime in seconds. Defaults to one week. |

**Returns**

Returns `Promise<CompleteOidcRedirectAuthResult>` in automatic mode, or `Promise<PendingWalletSelection>` in manual mode.

## Sign In With OIDC Redirect

Use this browser convenience wrapper when one call should start auth on normal pages and complete auth on callback pages.

```typescript theme={null}
const result = await oms.wallet.signInWithOidcRedirect({
  provider: 'google',
})

if (result && 'walletAddress' in result) {
  console.log('Wallet address:', result.walletAddress)
}
```

**Parameters**

| Parameter                | Type                                  | Description                                                                                                    |
| ------------------------ | ------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `provider`               | Provider name or provider config      | Use `google` for Google redirect auth.                                                                         |
| `redirectUri`            | `string` or undefined                 | App callback URL. Defaults to the current browser URL without OIDC callback params.                            |
| `walletType`             | `WalletType` or undefined             | Optional wallet type. Defaults to `WalletType.Ethereum`.                                                       |
| `walletSelection`        | `'automatic'` or `'manual'`           | Defaults to `'automatic'`.                                                                                     |
| `authorizeParams`        | `Record<string, string>` or undefined | Extra authorization query parameters passed to the provider.                                                   |
| `loginHint`              | `string` or undefined                 | Optional Google `login_hint` passed when starting redirect auth.                                               |
| `sessionLifetimeSeconds` | `number` or undefined                 | Optional requested wallet API session lifetime in seconds when completing redirect auth. Defaults to one week. |
| `cleanUrl`               | `boolean` or undefined                | Whether callback completion should clean the URL. Defaults to `true`.                                          |
| `currentUrl`             | `string` or undefined                 | Explicit current URL for non-browser routing flows.                                                            |
| `assignUrl`              | URL assignment callback or undefined  | Custom redirect function. Defaults to `window.location.assign`.                                                |
| `replaceUrl`             | URL replacement callback or undefined | Custom callback URL cleanup function.                                                                          |

**Returns**

Returns `Promise<CompleteOidcRedirectAuthResult | PendingWalletSelection | void>`.

## Use Wallet

Activate an existing wallet by server-side wallet ID.

```typescript theme={null}
await oms.wallet.useWallet({ walletId: 'wallet-id' })
```

**Parameters**

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

**Returns**

Returns `Promise<WalletActivationResult>`.

## Create Wallet

Create and activate a new wallet for the authenticated user.

```typescript theme={null}
const result = await oms.wallet.createWallet({
  reference: 'main',
})

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

**Parameters**

| Parameter   | Type                      | Description                                               |
| ----------- | ------------------------- | --------------------------------------------------------- |
| `type`      | `WalletType` or undefined | Wallet type to create. Defaults to `WalletType.Ethereum`. |
| `reference` | `string` or undefined     | Optional app-defined wallet reference.                    |

**Returns**

Returns `Promise<WalletActivationResult>`.