Akoya APIs overview

Introduction

Enable financial planning and budgeting tools, investment management, payment enablement, account opening, lending, credit enhancement, and more with consumer permissioned data obtained with Akoya's data APIs.

Authentication APIs

Our authentication APIs include our two token APIs. The Token API allows you to generate ID and refresh tokens to retrieve end user data from our data APIs. The Service token API generates access tokens for use with our service APIs.

Token API

Endpoint

Token

• Use to obtain and refresh ID tokens for our data APIs.

Revoke

• Use to revoke tokens on behalf of the consumer.

Service Token API

Endpoint

Service token

• Generate access tokens for our service APIs.

Data APIs

Our data APIs allow you to retrieve permissioned consumer data from financial institutions. Our APIs can be combined to meet a variety of use cases.

Account Information

Endpoint

Account information

• Gets basic account info such as accountId, masked account number, type, description, etc.

Balances

Endpoint

Balances

• Get balance info and interest rates for bank accounts, credit cards, loans, investments, and more.

Transactions

Endpoint

Transactions

• Get account transaction history.

Investments

Endpoint

Accounts

• Get the data returned in Balances and Account Information plus contributions, holdings, vesting information, and more.

Endpoint

Taxlots

• The taxlots endpoint allows you to retrieve tax lots of consumer-permissioned accounts.

Customers

Endpoint

Customer information

• Get customer data for the permissioned consumer

Account holder information

• Get customer data for ALL account holders.

Payments

Endpoint

Payments

• Includes account payment information such as bankId, identifier, type, and identifierType. This cluster supports use cases such as payment enablement and account opening.

Statements

Endpoint

Statement list

• Get a list of available account statement for the consumer’s consented accounts.

Statement

• Get a specific statement file in PDF format.

Service APIs

We provide three service APIs: Apps Management API, Notifications API, and Consent API.

Apps Management API allows you to create and manage applications on the Akoya network. Notifications API enables you to receive notifications about outages and other significant status changes on the network. Consent API allows you to receive notifications of an end user’s change in consent.

Apps Management API

Endpoint

Create app

• Create new apps on our network (up to 50 per request).

Update app

• Update your app details.

Get all apps

• Get a list of your created apps.

Get purchased clusters

• Get a list of your subscribed Akoya clusters.

Get valid providers For clusters

• List all providers that support an Akoya cluster.

Get subscriptions for app

• Get details for a specific app’s data provider subscription.

Get subscriptions for app - filter by status

• Get a list of your data provider subscription status for each provider.

Notifications API (BETA)

Endpoint

Create notification subscription

• Create a notification subscription to a specific category and type of notification.

List notification subscriptions

• Get a list of your notification subscriptions.

Get notification subscription by Id

• Get a specific notification subscription.

Delete notification subscription

• Delete a notification subscription.

Update notification subscription

• Update the callback URL, effective date, or callback email of a notification subscription.

Maintenance notification details

• Get the details of a specific notification.

Send sandbox test event

• Validate that your server can handle incoming webhook payloads from Akoya.

Consent API

Endpoint

Get consent grant

• Get the details of an end user’s change in consent.

Authentication

This section covers the basics of our authorization flow and how it works.

Tokens

Akoya has two types of tokens you may need to interact on the network:

• Tokens for our data APIs, generated with the Token API.

• Tokens for our service APIs, generated with the Service Token API.

Data API tokens

These tokens allow you to retrieve customer data from financial institutions via Akoya. For more details, see the Authorization flow and Token API sections.

Service API tokens

These tokens allow you to use our service APIs, such as the Apps Management API and the Notifications API. See Service tokens for more details.

Authorization Flow

In order to integrate an consumer’s data into your app, the user must first authenticate with their financial institution and authorize their data to be shared.

At a high level, the authentication flow follows these steps:

1. Your app sends the consumer to their provider’s sign in page via Akoya using a specific URL with required parameters for authentication. Required parameters are connector, client_id, redirect_uri, response_type, and scope.

2. The consumer completes account selection, agrees to terms with their provider, and then Akoya redirects the consumer to your app’s redirect_uri with an authorization code in the URL.

3. The authorization code is then used to retrieve a set of tokens from the Token endpoint that allow you permissioned access to the consumer’s data.

Token API

After your app receives an authorization code, there are two API endpoints available via the Token API for token management:

• Token - this endpoint allows you to obtain id and refresh tokens initially as well as refresh them. It will return a JWT token.

• Revoke - nullifies a previously granted token.

Service token API

The Management, Consent, and Notifications APIs require service (access) tokens. You'll need a client id and secret to create a service token, which you can obtain in the Data Recipient Hub. Once you have credentials, use the service token endpoint to generate an access token which will last for 24-hours. After it expires, you will need to use your client id and secret to generate a new service token.

Troubleshooting

Common errors encountered during authentication and data access include:

• “Bad Request” (browser error)

  • Returned if you’re trying to use an unregistered redirect URI.

• invalid_request

  • Returned when requesting ID and refresh tokens if your authorization code is expired.

• 601 “Customer not found”

  • May be returned if the customer revokes access or the ID token expires.

For more information on the errors returned by our APIs, please see

Error codes [Link not found]