Postman Getting Started

These instructions are compatible with Postman v8.2.1+


Your Environment

To use the Akoya API v1 collection, please ensure the parameters in your environment file are correct.


Akoya provides secure (TLS v1.2) access to RESTful APIs that are based on the API/Data Structures as defined by the Financial Data Exchange. All data requests use standard GET and POST methods and must include a bearer token in the authorization header. All responses are returned in JSON format.


End-user Authentication

In order for you to get end-user’s data, the first step is for the end-user to authenticate with their data provider. The process begins with your application sending the end-user to the provider’s login page via the Akoya platform.

After the end-user authenticates with their provider, the provider asks the end-user whether they are willing to grant the provider permission to share their data with 3rd parties (terms and conditions to which the end-user must agree). If the end-user does not agree to the provider's term and conditions, then Akoya will send the end-user back to your application (to the page of your choosing).

After authentication, your application is issued two tokens (id and refresh) from Akoya that gives you permissioned access to the end-user's data.


📘

Mikomo Financial

For your convenience, Akoya has made available Mikomo Bank, a mock financial institution, with test users and data. To see the collection of users, visit Mikomo.


Get started in four easy steps:

  1. Authorization
  2. Account selection
  3. Tokens
  4. Get data!

1️⃣ Authorization

In the “Authorization” folder, you will find an “Authorization Code” request. This request is not an endpoint but is for building the URL to start the end-user’s consent flow from your browser.

Select the documentation icon on the right, copy the URL at the top of the tab, and paste into your browser.

Use the URL at the top of the 'Authorization Code' documentation tab to start the consent flow processUse the URL at the top of the 'Authorization Code' documentation tab to start the consent flow process

Use the URL at the top of the 'Authorization Code' documentation tab to start the consent flow process


2️⃣ Account selection

Sign in as a Mikomo user (See Mikomo test users).


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

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


After account selection, you will be redirected to the URL provisioned in the Data Recipient Hub as your redirect_uri. Copy the code parameter from the URL.


Copy the string after “code=” in the URLCopy the string after “code=” in the URL

Copy the string after “code=” in the URL


3️⃣ Tokens

Akoya uses OIDC on top of OAuth 2.0

To ensure data privacy and consumer authorization, the Akoya Data Access Network (DAN) requires use of OAuth 2.0, Open ID Connect (OIDC), and JSON Web Tokens (JWT). The OAuth 2.0 access token is held by Akoya to communicate with the data provider. Akoya will issue you (the data recipient) an id token and refresh token. These tokens are used to communicate with the DAN.

Token Durations

TypeTest Environment Validity
Authorization Code5 minutes
ID Token30 minutes
Refresh TokenNo Expiration

Enter the code value (retrieved in step 2) in the body of the “Token” request and hit send. A successful result will update the id_token and refresh_token in your Postman environment.

Enter the `code` value in the body of the “Token” requestEnter the `code` value in the body of the “Token” request

Enter the code value in the body of the “Token” request


4️⃣ Get data!

You may now make account requests for this end-user. Endpoints for v4.1 are included.

Example v4.1 lightweight accounts responseExample v4.1 lightweight accounts response

Example v4.1 lightweight accounts response


To test transactions, be sure the test account includes transactions (See Mikomo test users).


Transactions v1 requires the `accountId` in the body of the requestTransactions v1 requires the `accountId` in the body of the request

Transactions v1 requires the accountId in the body of the request

*Transactions v4.1 requires the `accountId` in the parameters of the API call**Transactions v4.1 requires the `accountId` in the parameters of the API call*

Transactions v4.1 requires the accountId in the parameters of the API call