> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ownid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Elite flow

> Launch OwnID-hosted authentication in native Android and iOS apps with Elite flow.

Elite flow presents an OwnID-hosted authentication experience in an SDK-managed WebView. Use it when OwnID should provide the primary authentication UI and your app should handle only the native handoff points.

## Before you start

* Complete the Core SDK setup for [Android](/mobile-sdks/setup/android) or [iOS](/mobile-sdks/setup/ios).
* Complete [Passkey setup](/mobile-sdks/setup/passkeys).
* Register only the providers used by your hosted experience, such as `sessionCreate`, `passwordAuthenticate`, or supported social sign-in providers. See [Android providers](https://github.com/OwnID/ownid-android-sdk/blob/master/docs/setup/providers.md) or [iOS providers](https://github.com/OwnID/ownid-ios-sdk/blob/master/docs/setup/providers.md).
* Keep your app's existing authentication, registration, and session paths available for native handoff, hosted errors, and user close.

## How Elite flow works

The OwnID Web SDK runs the hosted experience in a WebView managed by the native SDK. WebBridge forwards the hosted page's terminal events to your app, where you complete any registration or session work that remains app-owned.

Elite flow reports two kinds of results:

* **Hosted events** describe what happened in the authentication experience. Handle the business outcome in `onNativeAction`, `onFinish`, `onError`, or `onClose`.
* **Controller results** describe how the native WebView run settled. Use `whenSettled()` for cleanup, cancellation, and SDK or WebBridge failures.

## Start Elite flow

Configure the hosted event callbacks, start the flow, and retain the returned controller until it settles.

<Tabs>
  <Tab title="Android" icon="android" iconType="brands">
    ```kotlin wrap theme={null}
    val context = EliteFlowContext {
        events {
            onNativeAction { loginId, ownIdData, accessToken ->
                // Complete an app-owned step, such as registration.
            }
            onFinish { loginId, authMethod, accessToken ->
                // Create or restore the app session.
            }
            onError { error ->
                // Show app-owned error or fallback UI.
            }
            onClose {
                // Return the app UI to an idle state.
            }
        }
    }

    val controller = OwnId.flows.elite.start(context)

    viewModelScope.launch {
        controller.whenSettled()
            .onSuccess {
                // A hosted terminal callback completed; clean up the flow.
            }
            .onCanceled { reason ->
                // Return to an idle or retry state.
            }
            .onError { error ->
                // Handle an SDK or WebBridge infrastructure failure.
            }
    }
    ```
  </Tab>

  <Tab title="iOS" icon="apple" iconType="brands">
    ```swift wrap theme={null}
    let context = EliteFlowContext { builder in
        builder.events { events in
            events.onNativeAction { loginID, ownIdData, accessToken in
                // Complete an app-owned step, such as registration.
            }
            events.onFinish { loginID, authMethod, accessToken in
                // Create or restore the app session.
            }
            events.onError { error in
                // Show app-owned error or fallback UI.
            }
            events.onClose {
                // Return the app UI to an idle state.
            }
        }
    }

    let controller = OwnID.flows.elite.start(context)

    Task { @MainActor in
        await controller.whenSettled()
            .onSuccess {
                // A hosted terminal callback completed; clean up the flow.
            }
            .onCanceled { reason in
                // Return to an idle or retry state.
            }
            .onError { error in
                // Handle an SDK or WebBridge infrastructure failure.
            }
    }
    ```
  </Tab>
</Tabs>

## Handle hosted events

| Callback         | When it runs                                                           | What your app should do                                                                                                                            |
| ---------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `onNativeAction` | The hosted page needs an app-owned native step, commonly registration. | Complete that step. For registration, keep the returned login ID and any `ownIdData` together, and send `ownIdData` unchanged when present.        |
| `onFinish`       | Hosted authentication completed successfully.                          | Complete the app authentication handoff and create or restore the app session. Use the optional Access Token only if your integration requires it. |
| `onError`        | The hosted page reported an application-level error.                   | Show an app-owned error or fallback state. Treat the optional error string as hosted-page context, not an SDK failure.                             |
| `onClose`        | The hosted page reported a close event.                                | Clear transient flow state and return the app to its idle UI.                                                                                      |

<Info>
  When present, `ownIdData` is an opaque OwnID authentication payload used to connect a native registration step to the hosted flow. Store it only with the matching login ID, send it unchanged with the registration request, and do not inspect or modify it.
</Info>

Hosted callbacks are terminal. After a callback returns successfully, the SDK closes the WebView and the controller settles successfully.

## Handle the controller result

| Result   | Meaning                                                                                                                | What your app should do                                                        |
| -------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| Success  | A hosted terminal callback completed. This can follow `onFinish`, `onNativeAction`, `onError`, or `onClose`.           | Clean up the running flow. Do not treat this result as authentication success. |
| Canceled | The app or SDK canceled the flow, the SDK shut down, or the WebView ended before a hosted terminal callback completed. | Clear the controller and return to an idle or retry state.                     |
| Failure  | The SDK, WebBridge, or WebView could not start or complete the native run.                                             | Show fallback UI and keep another authentication path available.               |

<Warning>
  A successful `whenSettled()` result does not mean authentication succeeded. Handle successful authentication in `onFinish` and app-owned registration in `onNativeAction`.
</Warning>

Treat Access Tokens, provider tokens, session payloads, `ownIdData`, and full hosted-event payloads as sensitive. Never log them.

## Continue with the full guides

<Columns cols={2}>
  <Card title="Android Elite flow guide" icon="android" iconType="brands" href="https://github.com/OwnID/ownid-android-sdk/blob/master/docs/flows/elite-flow.md">
    Complete event handling, controller behavior, providers, customization, and failures.
  </Card>

  <Card title="iOS Elite flow guide" icon="apple" iconType="brands" href="https://github.com/OwnID/ownid-ios-sdk/blob/master/docs/flows/elite-flow.md">
    Complete event handling, controller behavior, providers, customization, and failures.
  </Card>
</Columns>