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

> Establish an OMS Wallet credential and activate a wallet with email or OIDC.

Authentication establishes a wallet credential. Wallet selection then turns that credential into an active wallet session. Protected wallet operations remain unavailable until a wallet is active.

All auth completion methods use automatic wallet selection by default. Automatic selection activates the first existing Ethereum wallet, or creates and activates one when none exists.

## Use browser redirect sign-in

`signInWithOidcRedirect` is the normal browser path for Google and Apple. Call `completeOidcRedirectAuth` when your application loads, then start the redirect from your sign-in UI.

```typescript theme={null}
import {
  OMSWallet,
  OmsRelayOidcProviders,
} from '@polygonlabs/oms-wallet'

const omsWallet = new OMSWallet({
  publishableKey: 'YOUR_PUBLISHABLE_KEY',
})

await omsWallet.wallet.completeOidcRedirectAuth()

if (omsWallet.wallet.walletAddress) {
  console.log('Active wallet:', omsWallet.wallet.walletAddress)
}

// Run this from the user's Google sign-in action.
await omsWallet.wallet.signInWithOidcRedirect({
  provider: OmsRelayOidcProviders.google,
})
```

In a browser, the SDK uses the current page as the app return URL unless you pass `omsRelayReturnUri`. The wrapper stores transient redirect state, builds the authorization request, and navigates with `window.location.assign`. Callback completion validates the stored state, removes callback parameters from the browser URL by default, and returns `undefined` when the current URL is not the matching callback.

`OmsRelayOidcProviders.google` and `OmsRelayOidcProviders.apple` are fixed OMS relay providers. Their client IDs, provider callback URLs, scopes, auth modes, and authorization parameters are SDK-owned and cannot be configured. Use a custom provider configuration when your application owns those settings.

## Authenticate with email OTP

Email authentication separates code delivery from code verification so your application can render its own OTP form.

```typescript theme={null}
await omsWallet.wallet.startEmailAuth({
  email: 'user@example.com',
})

const result = await omsWallet.wallet.completeEmailAuth({
  code: '123456',
})

console.log(result.walletAddress)
console.log(result.credential.expiresAt)
```

`startEmailAuth` sends the code and keeps the pending attempt in memory. `completeEmailAuth` returns the active wallet, all wallets returned during auth, and the credential created by the flow.

## Authenticate with a provider ID token

Use `signInWithOidcIdToken` when your application already received an ID token from an identity provider SDK or another provider flow. This `idToken` is provider-issued input that OMS validates. It is not the OMS Wallet ID token that `getIdToken` later issues for your backend.

```typescript theme={null}
const result = await omsWallet.wallet.signInWithOidcIdToken({
  idToken: providerIdToken,
  issuer: 'https://accounts.google.com',
  audience: 'YOUR_WEB_CLIENT_ID',
  provider: 'google',
  providerLabel: 'Google',
})

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

The application must obtain `providerIdToken` itself and pass the exact issuer and audience used to mint it. `provider` and `providerLabel` only add display metadata to the completed session.

## Control browser routing directly

Use the lower-level pair when your router or navigation layer must inspect the authorization URL before redirecting.

```typescript theme={null}
const { authorizationUrl } = await omsWallet.wallet.startOidcRedirectAuth({
  provider: OmsRelayOidcProviders.google,
  omsRelayReturnUri: `${window.location.origin}/auth/callback`,
})

window.location.assign(authorizationUrl)

// On /auth/callback:
const result = await omsWallet.wallet.completeOidcRedirectAuth()
```

For fixed relay providers, `omsRelayReturnUri` is your application callback. The OAuth provider itself returns to an OMS-owned relay URL derived from the publishable-key environment.

## Configure a custom OIDC provider

A custom provider sends the OAuth callback directly to its `providerRedirectUri`.

```typescript theme={null}
import { type CustomOidcProviderConfig } from '@polygonlabs/oms-wallet'

const provider = {
  clientId: 'YOUR_WEB_CLIENT_ID',
  issuer: 'https://issuer.example.com',
  authorizationUrl: 'https://issuer.example.com/oauth2/authorize',
  providerRedirectUri: `${window.location.origin}/auth/callback`,
  provider: 'corporate',
  providerLabel: 'Corporate SSO',
  scopes: ['openid', 'email', 'profile'],
} satisfies CustomOidcProviderConfig

await omsWallet.wallet.signInWithOidcRedirect({ provider })
```

Custom providers default to authorization code with PKCE. The custom configuration owns scopes and default authorization parameters; per-call `authorizeParams` can add or override custom-provider parameters.

## Set credential lifetime

Completed auth requests ask for a one-week credential by default. Use `sessionLifetimeSeconds` to request an integer lifetime from 1 second through 2,592,000 seconds, or 30 days. The service can enforce its own result.

For email, pass it to `startEmailAuth`. For OIDC ID-token auth, pass it to `signInWithOidcIdToken`. For redirects, pass it when starting the flow; callback completion uses the stored value unless you override it there.

## Present your own wallet selector

Pass `walletSelection: 'manual'` when your application must choose or create a wallet after identity verification.

```typescript theme={null}
await omsWallet.wallet.startEmailAuth({ email: 'user@example.com' })

const selection = await omsWallet.wallet.completeEmailAuth({
  code: '123456',
  walletSelection: 'manual',
})

const existingWallet = selection.wallets[0]

const activeWallet = existingWallet
  ? await selection.selectWallet({ walletId: existingWallet.id })
  : await selection.createAndSelectWallet({ reference: 'main' })

console.log('Active wallet:', activeWallet.walletAddress)
```

Manual completion returns `PendingWalletSelection`. It contains a verified credential and wallet choices, but it is not an active wallet session. Complete that specific pending object with `selectWallet` or `createAndSelectWallet`. Starting another auth flow, signing out, expiring the credential, or completing a selection makes the pending object stale.

The same `walletSelection` option is available for email, OIDC ID-token, and OIDC redirect completion.

<Warning>
  Starting a new auth flow clears the current local wallet session before authentication continues. Do not use a sign-in action as an account-linking operation.
</Warning>

See [sessions and access](/wallets/sdk/typescript/sessions-and-access) for restored state, non-browser redirect storage, wallet switching, OMS Wallet backend ID tokens, revocation, and sign-out.