Native App Integrations
Native app integration is the process of interconnecting 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 an installed app is registered 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 consumer is redirected back to the platform. The platform checks to see if an installed app is registered 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 an installed app is registered 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 is redirected to 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 /sandbox/auth, which then guides the consumer to the provider bank login screen.
It is recommended that in-app browsers such as ASWebAuthenticationSession (iOS 13+), SFSafariViewController (iOS < 13), Chrome Custom Tabs, or external browsers are used when your application opens the provider’s login screen.
The graphic below illustrates the initial redirect consumer experience.
The optional screen is required to satisfy the Universal Link policy. This policy is enforced by iOS on Apple devices. It is not required for Android devices.
After the consumer authentication is verified by the provider, the consumer is redirected 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 /sandbox/token.
An optional account linking confirmation page is displayed prior to redirecting the consumer to your application’s Universal/App Link.
This experience is illustrated in the following example.
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 consumers are redirected. 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 stay on the server side. This helps prevent leakage. And in the event of a clientId/secret reset, your app recovers with consumers only needing to re-authenticate. If credentials were housed 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 ASWebAuthenticationSession (iOS 13+), 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.
Development resources
Changelog
Date | Update |
2025-Jan-02 | Original |