Onboarding: Getting started

The Akoya Data Access Network (DAN) allows you to connect your app with end-user data from providers available on the network. Akoya provides a sandbox for integrating and testing. The following steps outline how to get started in the sandbox.

1. Review best practices

First, review the Requirements & best practices guide to understand considerations for joining the Akoya network.

2. Join the Akoya Data Recipient Hub

🚧

Access Required

For access to the Akoya sandbox, you must have an account in the Data Recipient Hub.

Request a Hub account by filling out our request form.

The Data Recipient Hub is an Akoya application for managing your connections in the Akoya DAN. These connections are represented with apps you create in the Hub and their associated credentials (client_id and client_secret).

When this step is complete, you will have a Data Recipient Hub account. Check out our Data Recipient Hub User Manual to learn more about The Hub and what you can do in it.

3. Get your sandbox credentials

Once you have an account in the Hub, create your Akoya sandbox app. Your redirect_uri is needed for this step.

Your redirect URI specifies where the end-user is sent after they authenticate with their financial institution. Usually, this is your app. To prevent malicious redirects, your redirect URI must be registered with Akoya. You may use your live application endpoint or a resource in your local dev environment (https://localhost).

🚧

Localhost redirect supported in sandbox

Using the secure HTTPS protocol, the redirect URI in sandbox may use a localhost.

Redirection overview

Redirection overview

For more details on redirection, refer to the OAuth 2.0 RFC section: Redirection Endpoint.

4. Test token flow

A detailed explanation of token flow is available in the Token flow documentation.

To test in sandbox (For more, see: Sandbox), you must emulate how an end-user consents and selects accounts to share with your app. For this emulation, you may start this consent flow as a user of the Akoya sandbox mock provider, Mikomo Bank.

To create the URL for authorization, see Get Authorization Code and Akoya scope values.

Or, use the URL below, replace the CLIENT_ID and REDIRECT_URI with your own, and paste in a browser.

Note: The sandbox default redirect URI is used in this example. If your app is using https://recipient.ddp.akoya.com/flow/callback you only need to replace your client id.

https://sandbox-idp.ddp.akoya.com/auth?connector=mikomo&response_type=code&client_id=YWsxNTkxOTA1MEAtMTg6&redirect_uri=https://recipient.ddp.akoya.com/flow/callback&scope=openid%20offline_access&state=appstate

You will be prompted with a Mikomo login screen. Sign in as a Mikomo end-user.

Use:

username: mikomo_14

password: mikomo_14

Sign in, accept the user agreement, and select which accounts to share

Sign in, accept the user agreement, and select which accounts to share

5. Copy Authorization code

After signing in, select accounts to share and accept terms & conditions.

You are redirected by Akoya to your registered redirect_uri and a web page featuring the authorization code. Use the Copy code button on the web page to copy your authorization code. The authorization code is displayed in the Copy code dialog box and also in the URL sent back to the RedirectURI.

Copy the authorization code with the Copy code button

Copy the authorization code with the Copy code button

🚧

Authorization code timeout

You have 1 minute to copy the authorization code from the web page. The authorization code times out completely in 5 minutes. You must use it to request a token within 5 minutes or you will need to restart the consent flow.

When this step is complete, you will have values for the following parameters: client_id, client_secret, redirect_uri, connector/providerId and code.

6. Request tokens

Use the authorization code retrieved above, your client_id, client_secret, and redirect_uri with the Token API to request the id_token and refresh_token associated with the end-user.

Refer to the Tokens API token endpoint:

When this step is complete, you will have values for the following parameters: client_id, client_secret,redirect_uri, connector/providerId, refresh_token and id_token.

7. Obtain data

With the id_token obtained in Step 4, make a request with Akoya API v2 for the end-user's account data.

Refer to the Akoya API v2 Accounts info endpoint:

When this step is complete, you will have test data for this end-user.

8. βœ… Success!

You now have a familiarity with the account selection process and data retrieval. Your next step is to create your integration plan.

Welcome to Akoya!


Change log

DateUpdate
2023-Sep-20Adding HTTPS requirement for localhost
2022‑Feb‑24Added general clarification updates; added a form to generate authorization URLs
2024-Jan-12new first screenshot, fixed typos, added mikomo_14 and removed table