Getting Started

Learn how to place your first call for consumer data using the data APIs.

Prerequisites

You should have the following before starting this exercise:

1. A Data Recipient Hub account. A team lead or equivalent should set up a company account in the Data Recipient Hub and add you as a team member from “My Company."

2. Sandbox app with client ID and secret (API credentials). Obtain these from the Data Recipient Hub when you register your sandbox app. You can use the demo redirect URI https://recipient.ddp.akoya.com/flow/callback. If you need help, see the “Need help?” section.

Use Case

Emily is a user of your app, and she wants to link to her bank accounts at Mikomo Financial so she can view personal financial data from your app. You'll leverage Akoya’s APIs to ensure data is shared in a safe manner.

Emily authenticates to Mikomo Financial via Akoya. She enters her credentials on Mikomo’s authentication page and specifies which accounts she wants to share with your app. Once completed, she’ll return to your app’s redirect URI. At this point, your app can retrieve her data using the financial data API products.

What You'll Do

1. Obtain an authorization code. During this process, you will use a test account, GenericUser_Pfm, to emulate Emily granting permission to Mikomo Financial to send her financial data to your app via Akoya.

2. Exchange the authorization code for an ID token and a refresh token. The ID token proves that Emily has granted your app permission to pull her financial data from Mikomo Financial via Akoya. You use the refresh token to retrieve a new ID token after the latter expires.

3. Obtain Emily’s financial data. You’ll first make a call for all account data, and then you’ll retrieve data for a single account.

Read steps 1 and 2 before starting. The authorization code expires after five minutes and ID tokens expire after about 15 minutes, so you’ll have to work quickly.

Step 1: Obtain an Authorization Code

Emily has previously chosen to connect to Mikomo Financial. In this step, your app redirects her to Mikomo’s sign in page via Akoya where her financial institution prompts her to enter her sign in credentials and grant permission for account access. When she’s done, an authorization code generates. You use Akoya’s sandbox identity server to obtain the code since you're dealing with test data.

Obtain an auth code by pasting this into a browser. Substitute {{clientId}} with your value.

Your app has just directed Emily to Mikomo Bank to grant her consent for account access. Use the test user GenericUser_Pfm to authenticate. Enter GenericUser_Pfm as the username and password.

You, acting as Emily, are asked to select the accounts to share. Once you click “Approve,” you're taken to your app’s redirect URI. This action also returns the authorization code grant. The Token API uses the authorization code instead of a password to obtain ID and refresh tokens.

The authorization code will appear in the browser window. Copy it to your favorite text editor. You must exchange it for ID and refresh tokens within five minutes.

Step 2: Obtain ID and Refresh Tokens

In this step, you use the Token API to exchange the authorization code for a set of ID and refresh tokens. You’ll need the ID token to request data from Mikomo via Akoya.

How the Token Flow Works

Emily has selected Mikomo Financial, signed in to Mikomo’s authorization portal, and granted permission for your app to have access to account data. Your app receives an authorization code. You then exchange the authorization code for ID and refresh tokens. The ID token is a short-lived token the data APIs use to retrieve account data, and the Token API uses the refresh token to issue a new ID token when the latter expires.

A JSON object appears on the screen containing the ID and refresh tokens. Copy the ID token to your favorite text editor, as you’ll need it to retrieve data.

Troubleshooting

• If the authorization code expires, repeat Step 1.

• To reset a forgotten client secret, sign into the Data Recipient Hub.

Step 3: Obtain Data

You can now pull Emily’s account data from Mikomo. You’ll use the Account Information product in this example. The /accounts-info endpoint in this product retrieves basic account information including accountId, masked account number, type, description, etc.

The accountId is a unique account identifier used in place of a real account number. It’s used in many products to obtain data from specific accounts.

When used without a specific accountId, the /accounts-info endpoint pulls a list of all accounts. For this first data call, we don’t have any account IDs for Emily’s accounts, so we’ll call the endpoint without them to retrieve a list of all accounts.

The page will return a JSON object containing all accounts for GenericUser_Pfm.

Now, let’s say you just want Emily’s checking account information. All you need to do is repeat the call but specify the desired accountId in the accountIds query param this time:

Troubleshooting

If you receive this error, repeat Steps 1 and 2 to generate a new authorization code and set of tokens.

Congratulations

You successfully:

• Obtained an authorization code

• Exchanged the authorization code for an ID token

• Used the ID token to request data for a test user

Explore the API docs to learn more about Akoya's products.