--- title: Pairing in a DaVinci flow on Android description: Pair an Android device to PingOne MFA directly inside a DaVinci flow using the MOBILE_PAIRING collector, which the pingonemfa module registers automatically. component: orchsdks page_id: orchsdks:davinci:use-cases/pingone-mfa/android/02-automated-pairing canonical_url: https://developer.pingidentity.com/orchsdks/davinci/use-cases/pingone-mfa/android/02-automated-pairing.html llms_txt: https://developer.pingidentity.com/orchsdks/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md keywords: ["DaVinci", "MFA", "PingOne", "Android", "Pairing", "MOBILE_PAIRING", "Collector", "SDK"] section_ids: creating_the_pairing_flow: Creating the pairing flow registering_the_collector: Registering the collector handling_the_pairing_collector: Handling the pairing collector allowing_users_to_cancel_pairing: Allowing users to cancel pairing --- # Pairing in a DaVinci flow on Android [icon: circle-check, set=far]PingOne [icon: android, set=fab]Android Before a device can receive push notifications, generate OATH one-time passcodes, or perform automated authentication it must be registered with PingOne MFA. This registration is called pairing. The Orchestration SDK supports an automated pairing method by using the `pingonemfa` module, and a specialized DaVinci flow that leverages the [PingOne MFA](https://docs.pingidentity.com/connectors/p1_mfa_connector.html) connector. This DaVinci flow returns a `MOBILE_PAIRING` collector, and the `pingonemfa` module pairs the device behind the scenes, reporting the result back to the flow when your app submits the node. If the device is already paired, the same process authenticates the device instead. ## Creating the pairing flow Build the pairing flow in the DaVinci admin console using the PingOne connector and the PingOne MFA connector: 1. **Find the user** — add a [Find User](https://docs.pingidentity.com/connectors/p1_connector.html) capability from the PingOne connector to look up the user to pair. The capability takes an identifier such as a username or email address, and returns the matched user profile, including the user's `id`. 2. **Create the pairing key** — add a [Create Pairing Key](https://docs.pingidentity.com/connectors/p1_mfa_connector.html#createPairingKey) capability from the PingOne MFA connector, and map the user's `id` from the Find User node to its **User ID** input. The capability generates a one-time pairing key and returns the key's `code` and `id` in its response. 3. **Pair the device** — add a [Pair Mobile Device With Pairing Key](https://docs.pingidentity.com/connectors/p1_mfa_connector.html) capability from the PingOne MFA connector, and map the values returned by the Create Pairing Key node to its inputs: | Input | Value | | ------------------ | ----------------------------------------------- | | **Pairing Key** | The `code` from the **Create Pairing Key** node | | **Pairing Key ID** | The `id` from the **Create Pairing Key** node | The result resembles the following: ![davinci pingone mfa auto pairing pair mobile with pairing key configuration](../../../_images/davinci-pingone-mfa-auto-pairing-pair-mobile-with-pairing-key-configuration.png)Figure 1. Configuring the Pair Mobile Device With Pairing Key capability. When the flow reaches this node, it pauses and returns the `MOBILE_PAIRING` collector to your app, which pairs the device. 4. **Complete the flow** 1. Add a PingOne Authentication connector node with the [Return Success Response (Redirect Flows)](https://docs.pingidentity.com/connectors/p1_authentication_connector.html) capability, and connect the `True` path of the Pair Mobile Device With Pairing Key node to it. The **PingOne MFA** connector verifies the pairing result server-side before the flow resumes, so a `true` result means the device is paired and ready to receive push notifications and OATH challenges. 2. Connect the `false` path to a function node that reports the failure. The failure payload contains the native PingOne MFA SDK error code and message. Some of the error codes you may encounter are as follows: | Code | Meaning | | ----- | ---------------------------------------------------------------------------------------------------- | | 10003 | Server error, for example the PingOne MFA service is unreachable or returned an unexpected response. | | 10004 | No network connectivity on the device. | | 10005 | Problem with the pairing key, for example the key is invalid, expired, or has already been claimed. | | 10006 | Problem with the application ID, for example the app is not registered in the PingOne environment. | | 10007 | The device is already paired in a different regional data center. | | 10013 | A pairing operation is already in progress. | | 10017 | Failed to establish trust with the PingOne MFA server. | See [PingOne MFA SDK error codes](https://developer.pingidentity.com/pingone-api/native-sdks/pingone-mfa-mobile-sdks/pingone_mfa_sdk_errror_codes.html) in the PingOne Platform API documentation for the complete list. The resulting flow resembles the following: ![davinci pingone mfa auto pairing flow](../../../_images/davinci-pingone-mfa-auto-pairing-flow.png)Figure 2. Example DaVinci flow for automated PingOne MFA pairing. ## Registering the collector To process the `MOBILE_PAIRING` collector, your app registers the module's `MobilePairingCollector` with the DaVinci collector factory. Unlike the collectors built in to the Orchestration SDK DaVinci module, the `pingonemfa` module is a separate add-on module, so the DaVinci module does not register its collectors for you. In most apps no extra code is required: when you add the `pingonemfa` module as a dependency, an AndroidX app startup initializer registers `MobilePairingCollector` for you. Only if your app disables automatic initialization do you need to register the collector manually before starting any DaVinci flow: Registering the MOBILE_PAIRING collector ```kotlin CollectorFactory.register("MOBILE_PAIRING", ::MobilePairingCollector) ``` ## Handling the pairing collector The pairing collector works like other collectors in your flow, but it needs no user input. The collector receives the pairing key from the DaVinci flow automatically, so all your app has to do is call `collect()` to start the pairing, display a loading indicator while it runs, and call `node.next()` when it completes. Under the hood, `collect()` calls the module's `PingOneMFA.pair()` function with the pairing key from the flow: `collect()` is a `suspend` function, so call it from a coroutine, for example `viewModelScope.launch` or a Compose `LaunchedEffect`. Handling the MOBILE_PAIRING collector ```kotlin // Inside your collector rendering loop for a DaVinci node: when (val collector = node.collectors.firstOrNull { it is MobilePairingCollector }) { is MobilePairingCollector -> { // Show a spinner while the pairing is in flight showSpinner() // collect() starts the pairing val result = collector.collect() hideSpinner() result.onSuccess { // Pairing key claimed — submit the node node.next() }.onFailure { e -> // Show the error locally, then submit the node so the // collector reports the failure to the flow showError(e.message) node.next() } } } ``` | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | If you want to pair a device outside of a DaVinci flow, you can call `pair()` directly.Learn more in [Pairing with a QR code or pairing key](03-qr-code-pairing.html). | ## Allowing users to cancel pairing While the spinner is showing, you can offer a **Cancel** or **Back** button so users can skip pairing. If the user cancels, call `cancel()` on the collector, then call `node.next()` as usual: Canceling the pairing ```kotlin collector.cancel() // Then call node.next() as usual ``` The module reports the cancellation to the DaVinci flow as a failure with the code `USER_CANCELLED`, and the flow continues down its failure path. Calling `cancel()` does not stop a pairing that the PingOne MFA native SDK has already started; that pairing request runs to completion in the background and its result is discarded, so the cancellation is what the flow sees.