Native App Integrations
Native app integration interconnects one or two native apps for a seamless consumer experience. We’ll cover two primary use cases in this guide: app-to-web and app-to-app. The two primary mechanisms are the Android App Links and the Apple iOS Universal Links.
App-to-Web
Universal Links/App Links are standard web links http://example.com. Your app launches the /authorization URL. This triggers the platform (iOS/Android) to check and see if it has registered an installed app for that link. If so, the app launches (App-to-App). If not, the browser loads the linked web page (App-to-Web).
After the consumer successfully completes authorization with the data provider, the provider redirects the consumer back to the platform. The platform checks to see if it has registered an installed app for the link. In this case, your callback URL is registered as the link in the Apple App Site Association (iOS) or Digital Assets Links (Android) configuration. Your app picks up the link which contains the authorization code. The app can then proceed to exchange that code for the tokens.
App-to-App
The system supports universal linking to both the fintech app and the bank app. Much like the App-to-Web, your app launches the /authorization URL. The launch triggers the platform (iOS/Android) to check and see if it has registered an installed app for that link. If it finds the link, the platform immediately opens the bank app to allow for consumer authentication. At this point the bank app may choose to use a traditional login form, pass code, or biometrics to authenticate the consumer. Once the consumer has completed the authorization your app’s registered callback URL they redirect back to the platform. The platform finds your registered app, opens it, and passes the authorization code.
Native App Flow
These are the steps for the native app flow:
Your application registers the callback URL redirect_uri with the system using Universal Links/App Links.
Your application redirects the consumer to https://idp.ddp.akoya.com, which then guides the consumer to the provider bank login screen.
The Internet Engineering Task Force (IETF) recommends that you use in-app browsers such as SFSafariViewController (iOS < 13), Chrome Custom Tabs, or external browsers when your application opens the provider’s login screen.
This graphic illustrates the initial redirect consumer experience.
The optional screen satisfies the Universal Link policy. iOS on Apple devices enforces this policy. It is not required for Android devices.
After the provider verifies the consumer authentication, the consumer redirects back to the callback redirect_uri hosted page. This guides them with a prompt back to your application.
The callback hosted page handler exchanges the auth code to get the Akoya id_token and refresh_token at https://idp.ddp.akoya.com/token.
You can display an optional account linking confirmation page before redirecting the consumer to your application's Universal/App Link.
The following example illustrates this experience.
Not Using Universal Links/App Links (not recommended)
If you don't support Universal or App Links, you must provide a link to the application's secure website where the browser redirects consumers. From here, you can capture the authorization code and send the consumer back to the app. You can send them back with on screen instructions or private URI Schemas (not supported in the callback URL).
ClientId/Secret and Token Exchange
Best practice is to protect your clientId/secret by keeping them server-side. This helps prevent leakage. In the event of a clientId/secret reset, your app recovers with consumers only needing to re-authenticate. If you house credentials in app on the device, you would need to release an update. This would create an additional impact to your consumers.
It is recommended that any Akoya endpoint using clientId/secret take place via server-to-server communication. This improves security and stability.
Development Guidelines
The system does not support Custom (aka Private-Use) URI Schemes as callback URLs redirect_uri for data recipient applications.
Use Universal/App Links. These are more secure and reliable than custom URL schemes. Universal/App Links use standard web technologies and prevent URL hijacking.
Always open the auth URL in secure in-app browsers such as SFSafariViewController (iOS < 13), Chrome Custom Tabs, or external browsers.
Use your app’s Universal/App Link for the callback/redirect URL to redirect the consumer back to the mobile application.
Integrate with server-side calls when exchanging an auth code for an id_token and refresh_token to protect your client secret.