Tokens

To support authorization and ensure data privacy, Akoya uses tokens to verify end-user identity by leveraging the following standards:

• OAuth 2.0 Protocol that controls authorization to access a protected resource like a web app or API service.

• OpenID Connect (OIDC). Layer used over OAuth 2.0 that helps authenticate users and convey information about them.

• JSON Web Tokens (JWT). Standardized container format used to securely transfer data for authentication and authorization.

Consent flow

Authentication & authorization

For you to connect your end-user’s data to your app, the end-user must authenticate with their data provider (bank or financial institution) and authorize data to be shared. Initial authentication remains in effect until either the end-user revokes access to their data or their associated refresh token expires. Authorization and authentication (consent flow) follows these steps:

1. Your app sends the end-user to their provider’s login page via Akoya using a specific URL with required parameters for authentication. Required parameters are connector, client_id, redirect_uri, response_type, and scope. More details on required parameters are documented in Get authorization code. Possible values for the scope parameter are defined in the next section, Akoya scope values.

2. The end-user completes account selection and agrees to terms and conditions with their provider. Akoya then sends the end-user to your app’s redirect_uri. Akoya will include an authorization code in the URL when it redirects the end-user back to your app. This code will expire in 5 minutes.
   
   Example URL sent to your app with authorization code:
   https://recipient.ddp.akoya.com/flow/callback?code=vhmji7kmopeil4jyb57wc4znx&state=

3. With the authorization code and your app’s details, use the Token endpoint to retrieve a set of tokens (ID token and refresh token). These tokens allow you permissioned access to the end-user’s data.

OIDC

After the end-user completes account selection and provides consent (Consent flow: step 2 above), the provider issues an access token to Akoya. Akoya will issue your app an ID token (OIDC token—a signed JSON Web Token) and refresh token (Consent flow: step 3 above). Your app will use ID and refresh tokens to communicate with the Akoya network.

Tokens for each end-user are specific to their current account authorization from their provider. To change account selection, the end-user must go through the consent flow again to update the ID and refresh tokens.

For more on OpenID Connect core functionality, see OpenID Connect Core 1.0 incorporating errata set (https://openid.net/specs/openid-connect-core-1_0.html)

Akoya scope values

When your app sends the end-user through Akoya for authentication (Consent flow: step 1 above), the URL may include the following authorization scope values. Scope is used to define access and consent.

These scope types are supported by OIDC but not all may be present.

• openid - required. Specifies this is an OIDC identity request. Returns iss, sub, aud, exp, iat, and at_hash (defined below).
• email - Provides access to email and email_verified JWT claims
• groups
• profile - Requests access to end-user’s profile values including name
• offline_access - required. Requests a refresh token be issued

For more on OIDC scope values see: Requesting Claims using Scope Values.

Token usage

Your app will use two types of tokens, ID and refresh tokens.

ID token

The ID token is a short-term token used for requesting data from Akoya product endpoints. This token may be decoded to view identity token claims (see ID token details).

ID token lifetime

The ID token is short-lived. In the Akoya sandbox, the ID token may last 24 hours to facilitate testing. However, providers often have a shorter expiration for ID tokens. We recommend treating ID tokens as having a life of no longer than 15 minutes and coding to automatically refresh if the ID token has expired. To follow this recommendation, in the case of expiration or after an app uses an ID token for 15 minutes, make a refresh token call to renew the tokens.

Refresh token

The refresh token is longer-term and is tied to the end-user’s authorization. Refreshing tokens allows your app to replace an expired ID token without asking the end-user to reauthenticate and maintains authorization when the end-user is not actively using your app. This token cannot be decoded. See more details regarding refresh tokens below.

🚧

Refresh tokens replace themselves.

With every refresh token call, a new set of refresh and ID tokens will be returned.

Refresh token lifetime

Refresh tokens may be perpetual, have a rolling expiration, or have a set expiration from the date of authorization. In cases when a provider has rolling refresh token durations, implementing refresh token rotation is recommended.

Next, see:

• Refresh token details (below)

• Provider token expiration times are documented in the Data Recipient Hub

Sandbox tokens

In the Akoya sandbox, the ID token may last 24 hours to facilitate testing. However, some providers have a shorter expiration period. We recommend integrating ID tokens as having a life of no longer than 15 minutes and coding to automatically refresh if the ID token has expired.

ID token details

The ID token is a short-lived identifier for the end-user. This token is used as a bearer token with each request to an Akoya API v2 endpoint.

Example ID Token

{
  "iss": "https://sandbox-idp.ddp.akoya.com/",
  "sub": "CkExamplehtaWtvbP9fMRIGbWlrb21v",
  "aud": "recipient",
  "exp": 1626206304,
  "iat": 1626119904,
  "at_hash": "VZ_ExJP9zAhtWa5KxCTX-CQ",
  "email": "mikomo_1",
  "email_verified": false,
  "name": "KLDJFSDI4909DPSJNIO"
}

Akoya ID JWT Claims

These claim types are supported by Akoya but not all may be present.

• iss - Issuer of the JWT, Akoya
• sub - Unique value to identify the end-user with the scope specific to the data provider
• aud - Data recipient
• exp - Time token will expire in Unix Epoch format
• iat - The time the token was issued in Unix Epoch format
• at_hash - Access token hash value
• email - End-user’s email address
• email_verified - True if end-user’s email is verified, otherwise false
• name - End-user's name in displayable form
• locale - End-user's locale

For more: see the RFC on Identity Token claims.

Expired ID token errors

If you use an expired ID token with a product (data) endpoint, it will produce error code 602.

{
    "code": 602,
    "message": "Customer not authorized"
}

If you receive this error, you should refresh the tokens. Then, using the new ID token, make the call for data again.

Refresh token details

The encoded and longer-lived refresh token is used to obtain a new ID token without requiring the end-user to provide credentials or reauthenticate every time the ID token expires.

Refresh tokens are used with the Token API and not as a bearer token in Akoya product calls. A call to the Token API to refresh tokens issues new ID and refresh tokens. This refresh token rotation helps protect applications from token compromise.

The refresh token must be treated as highly confidential.

Encrypted storage is essential to avoid [cross-site scripting](https://www.owasp.org/index.php/Cross-site_Scripting(XSS)) (XSS) attacks._

Refresh token expirations

Some providers set an expiration time for refresh tokens so that a user must reaffirm they want to share their data. There are three types of token expirations:

Perpetual. If a token is perpetual, this means the provider has no set expiration date for the refresh token.

Set expiration. Some tokens have a set expiration period that forces reauthentication after the time indicated. This is commonly a year. After the token’s expiration, the end-user will need to go through the consent flow again.

A rolling expiration. A rolling token expiration means that the token duration is reset every time the token is used. For instance, if your end-user’s bank has specified a rolling 6-month token expiration, you can refresh tokens without reauthentication at any time before the six-month expiration. On refresh, the token expiration will reset to six months from that time. However, if your app hasn’t refreshed tokens in 6 months, the next time the end-user uses your app, they will need to go through the consent flow again.

Refresh token rotation

If your app rotates tokens before a rolling expiration date or if tokens expire and the end-user must go through the consent flow again, you may link the new refresh token with the end-user by matching the sub value in the ID token's JWT claims.

Refresh token error

If you make a request using the Token API with an expired refresh token, you will receive an invalid_request error.

{
    "error": "invalid_request",
    "error_description": "Refresh token is invalid or  has already been claimed by another client."
}

An expired refresh token requires the app to redirect the end-user back through the consent flow and account selection process to reauthorize and receive a new set of ID and refresh tokens. To match new refresh tokens to your end-user, please see Refresh token rotation above.

Example with expired tokens

If an app requests data through an Akoya product endpoint (such as Accounts Info) using an expired ID token, the app will receive a 602 error. The app should then send a refresh token request to the Token API. If the app then receives an invalid_request error (as seen above) from the token endpoint, this indicates the refresh token is also expired. In this case, the app should send the end-user back to through the consent flow.