Requirements & best practices

Tips for integrating your application with the Akoya Data Access Network.

We have a number of implementation requirements to ensure the security of our network and our end-users' financial data. Please review these requirements before continuing.

๐Ÿšง

Please donโ€™t skip this page!

Please take the time to go over all the resources in this section before moving on to the project checklists.

Requirements

  • A consent UX in your app

  • OIDC token use with secure, encrypted storage

  • Redirect URI(s)

    • The callback resource in your application where Akoya will send the end-user and authorization code after successful authentication
  • Secure, encrypted storage for your appโ€™s client_id, client_secret and all tokens

    • The client_secret should NEVER be hard-coded into your application's source code.

Best practices

๐Ÿ“˜

Scheduled maintenance window

Akoya has scheduled maintenance on Tuesdays from 10AM-1PM EST. Outages during this time should be expected, but minimal in nature. If you encounter issues during this time, please wait until the conclusion of the maintenance window to try again.

  • One Hub account. Your company should maintain one Data Recipient Hub team account. The first team member to join the Hub should send invitations to the remaining members of the team. See: Data Recipient Hub v5.

  • Token revocation. Provide a link for the end-user to revoke permission for use of their provider's accounts.

  • Pagination. Build a pagination component into your app, allowing it to receive one page at a time.

  • Provider guidelines. Adhere to implementation differences required by some data providers. These guidelines, and other integration considerations, are documented by provider in the Data Recipient Hub.

  • Outages. Please notify Akoya when major service disruptions occur that impact the network, such as an event that causes you to invalidate all tokens or forces re-authentication.

  • Errors.

    • For 500-level HTTP errors, We recommend implementing three (3) retries to help your app deal with short-lived, transient failures. The waiting time between retries should increase exponentially with each retry attempt.
  • Versioning. Akoya limits breaking changes to major API versions. To reduce the need for large, breaking-change updates, Akoya will continue to improve its products by releasing minor updates on a continual basis. These minor updates are non-breaking, backward-compatible improvements. When migrating to Akoya API v2, please plan for these minor version updates and implement in a way to allow for these non-breaking changes. See: Versioning.

  • Requests.

    • Send the x-akoya-interaction-type header with all Akoya product calls to indicate if the request is part of a batch process or a real-time, end-user interaction. See: Headers.
  • Responses.

    • Track the header x-akoya-interaction-id returned with each Akoya API request. See: Headers.
    • Your app should handle 206 HTTP Partial Responses.

FDX

Akoya API v2 is based on Financial Data Exchange (FDX) specifications (learn more about FDX here). The following FDX guidance is recommended while using Akoya API v2:

  • Utilize the FDX API, security, and user experience specifications.

  • Follow FDX version recommendations for API deprecation.

Recipients need not be members of FDX to integrate with the Akoya Data Access Network; however, FDX provides a variety of membership options. It also provides fee-free access to API specifications by accepting the intellectual property agreement.