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

# Kotlin SDK Authentication

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

The Kotlin SDK supports email OTP, OIDC ID-token authentication, and OIDC authorization-code redirect authentication. 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.

## Start Email Auth

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

```kotlin theme={null}
client.wallet.startEmailAuth("user@example.com")
```

**Parameters**

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

**Returns**

Returns `Unit`.

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

```kotlin theme={null}
import com.omsclient.kotlin_sdk.wallet.CompleteAuthResult

val result = client.wallet.completeEmailAuth("123456")
check(result is CompleteAuthResult.WalletSelected)

println("Wallet address: ${result.walletAddress}")
println("Wallet ID: ${result.wallet.id}")
```

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

```kotlin theme={null}
import com.omsclient.kotlin_sdk.wallet.CompleteAuthResult
import com.omsclient.kotlin_sdk.wallet.WalletSelectionBehavior

val selectionResult = client.wallet.completeEmailAuth(
    code = "123456",
    walletSelection = WalletSelectionBehavior.Manual,
)
check(selectionResult is CompleteAuthResult.WalletSelection)

selectionResult.pendingSelection.createAndSelectWallet(reference = "main")
```

**Parameters**

| Parameter         | Type                      | Description                                              |
| ----------------- | ------------------------- | -------------------------------------------------------- |
| `code`            | `String`                  | One-time code entered by the user.                       |
| `walletSelection` | `WalletSelectionBehavior` | Defaults to `WalletSelectionBehavior.Automatic`.         |
| `walletType`      | `WalletType`              | Optional wallet type. Defaults to `WalletType.Ethereum`. |

**Returns**

Returns `CompleteAuthResult`, either `WalletSelected` or `WalletSelection`.

## Sign In With OIDC ID Token

Use OIDC ID-token auth for providers such as Google Sign-In with Android Credential Manager.

```kotlin theme={null}
import com.omsclient.kotlin_sdk.wallet.CompleteAuthResult

val result = client.wallet.signInWithOidcIdToken(
    idToken = googleIdToken,
    issuer = "https://accounts.google.com",
    audience = "YOUR_WEB_CLIENT_ID",
)
check(result is CompleteAuthResult.WalletSelected)

println("Wallet address: ${result.walletAddress}")
```

**Parameters**

| Parameter         | Type                      | Description                                                   |
| ----------------- | ------------------------- | ------------------------------------------------------------- |
| `idToken`         | `String`                  | OIDC ID token from the identity provider.                     |
| `issuer`          | `String`                  | Expected token issuer, such as `https://accounts.google.com`. |
| `audience`        | `String`                  | Expected token audience.                                      |
| `walletSelection` | `WalletSelectionBehavior` | Defaults to `WalletSelectionBehavior.Automatic`.              |
| `walletType`      | `WalletType`              | Optional wallet type. Defaults to `WalletType.Ethereum`.      |

**Returns**

Returns `CompleteAuthResult`.

## Start OIDC Redirect Auth

Start an OIDC authorization-code PKCE flow and open the returned authorization URL in app-owned UI such as Custom Tabs.

```kotlin theme={null}
import com.omsclient.kotlin_sdk.wallet.OidcProviders

val redirect = client.wallet.startOidcRedirectAuth(
    provider = OidcProviders.google(),
    redirectUri = "com.example.app:/auth/callback",
)

openCustomTab(redirect.authorizationUrl)
```

**Parameters**

| Parameter          | Type                  | Description                                                  |
| ------------------ | --------------------- | ------------------------------------------------------------ |
| `provider`         | `OidcProviderConfig`  | OIDC provider configuration.                                 |
| `redirectUri`      | `String`              | App callback URL that receives the provider redirect.        |
| `walletType`       | `WalletType`          | Optional wallet type. Defaults to `WalletType.Ethereum`.     |
| `relayRedirectUri` | `String?`             | Optional OAuth redirect URI override.                        |
| `authorizeParams`  | `Map<String, String>` | Extra authorization query parameters passed to the provider. |

**Returns**

Returns `StartOidcRedirectAuthResult` with `authorizationUrl`, `state`, and `challenge`.

## Handle OIDC Redirect Callback

Pass incoming app-link URLs to the callback handler. It is safe to call from `onCreate` or `onNewIntent` for unrelated links.

```kotlin theme={null}
import com.omsclient.kotlin_sdk.wallet.OidcRedirectAuthResult

when (val result = client.wallet.handleOidcRedirectCallback(intent.data?.toString())) {
    is OidcRedirectAuthResult.Completed -> {
        println("Wallet address: ${result.wallet.address}")
    }
    is OidcRedirectAuthResult.WalletSelection -> {
        result.pendingSelection.createAndSelectWallet()
    }
    OidcRedirectAuthResult.NotOidcRedirectCallback -> Unit
    OidcRedirectAuthResult.NoPendingAuth -> Unit
    is OidcRedirectAuthResult.Failed -> throw result.error
}
```

**Parameters**

| Parameter         | Type                      | Description                                      |
| ----------------- | ------------------------- | ------------------------------------------------ |
| `callbackUrl`     | `String?`                 | Incoming app-link URL.                           |
| `walletSelection` | `WalletSelectionBehavior` | Defaults to `WalletSelectionBehavior.Automatic`. |

**Returns**

Returns `OidcRedirectAuthResult`.

## Use Wallet

Activate an existing wallet by server-side wallet ID.

```kotlin theme={null}
client.wallet.useWallet(walletId = "wallet-id")
```

**Parameters**

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

**Returns**

Returns `WalletSelectionResult`.

## Create Wallet

Create and activate a new wallet for the authenticated user.

```kotlin theme={null}
val result = client.wallet.createWallet(reference = "main")

println("New wallet: ${result.walletAddress}")
```

**Parameters**

| Parameter    | Type         | Description                                               |
| ------------ | ------------ | --------------------------------------------------------- |
| `walletType` | `WalletType` | Wallet type to create. Defaults to `WalletType.Ethereum`. |
| `reference`  | `String?`    | Optional app-defined wallet reference.                    |

**Returns**

Returns `WalletSelectionResult`.