Authentication & Authorization Basics

Authentication

Akoya uses bearer tokens for authentication. We have two types of tokens:

• ID tokens for the data APIs, generated with the Token API.

• Access tokens for the service APIs, generated with the Service Token API.

ID 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 Tokens

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

Authorization Flow

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 returns JWT tokens.

• 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 lasts for 24 hours. After it expires, you 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 expires.

• 601 “Customer not found”

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

For more information on the errors returned by the APIs, see API Error Reference.