> ## 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 and Google sign-in through OIDC ID-token authentication or 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.

```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 returns an active wallet when possible.

```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`.                         |
| `sessionLifetimeSeconds` | `Long`                    | Optional requested wallet API session lifetime in seconds. Defaults to one week. |

**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`.                         |
| `sessionLifetimeSeconds` | `Long`                    | Optional requested wallet API session lifetime in seconds. Defaults to one week. |

**Returns**

Returns `CompleteAuthResult`.

## Start OIDC Redirect Auth

Start a Google 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 = "yourapp://auth/callback",
)

openCustomTab(redirect.authorizationUrl)
```

Register an Android intent filter for the callback scheme, such as `yourapp`, before using redirect auth.

**Parameters**

| Parameter         | Type                  | Description                                                                                                                                 |
| ----------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `provider`        | `OidcProviderConfig`  | Google provider configuration returned by `OidcProviders.google()`.                                                                         |
| `redirectUri`     | `String`              | App callback URL that receives the provider redirect. Configure this URL scheme or app link with an Android intent filter.                  |
| `walletType`      | `WalletType`          | Optional wallet type. Defaults to `WalletType.Ethereum`.                                                                                    |
| `authorizeParams` | `Map<String, String>` | Extra authorization query parameters passed to the provider.                                                                                |
| `loginHint`       | `String?`             | Optional Google `login_hint`. When omitted for Google, the SDK can reuse the previous session email. Pass an empty string to force no hint. |

**Returns**

Returns `StartOidcRedirectAuthResult` with the provider `authorizationUrl`. `state` and `challenge` are SDK-managed values.

## 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`.                                 |
| `sessionLifetimeSeconds` | `Long`                    | Optional requested wallet API session lifetime in seconds. Defaults to one week. |

**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`.