Token flow

To ensure data privacy and consumer authorization, the Data Access Network requires use of OAuth 2.0, Open ID Connect (OIDC), and JSON Web Tokens (JWT).

To ensure data privacy and consumer authorization, the Akoya Data Access Network (DAN) requires use of OAuth 2.0, OpenID Connect (OIDC), and JSON Web Tokens (JWT).

  • OAuth 2.0 protocol controls authorization to access a protected resource like a web app or API service.
  • OIDC helps authenticate users and convey information about them.
  • JWT is a standardized container format used to securely transfer data for authentication and authorization.

Authentication and authorization

For access to end-user data, the first step is for the end-user to authenticate with the data provider where the data is held. This initial authentication remains in effect until either the end-user revokes access to their data or their refresh token expires. The authorization/authentication flow follows these steps:

  1. Your app sends the end-user to their data provider’s login page via the Akoya Data Access Network using a specific URL for authorization (see Get Authorization Code). Parameters used with the URL are defined in Akoya scope values (below).
  2. The end-user completes account selection and agrees to terms and conditions with the data provider. If the consumer does not agree to the provider's term and conditions, then Akoya will send the consumer back to your application (to the page of your choosing).
  3. Your app receives refresh and ID tokens from Akoya that gives you permissioned access to the end-user’s data (see below: Akoya uses OIDC on top of OAuth 2.0)

Akoya scope values

During authorization (step one above), you must request an authorization code using the following scope values:

These scope types are supported by Akoya 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

To learn more see: Requesting Claims using Scope Values

Akoya uses OIDC on top of OAuth 2.0

Auth flowAuth flow

Auth flow

After the end-user completes account selection and provides consent, the data provider issues an access token to Akoya. Akoya will issue you (the data recipient) an ID token (OIDC token—a signed JSON Web Token) and refresh token. Recipients 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 data provider. The account selection may be updated through their action either through the recipient app or through their provider (if the
provider has that functionality).

For more on OpenID Connect core functionality, see https://openid.net/specs/openid-connect-core-1_0.html

Token storage

Treat the refresh token as sensitive information. Each end-user token should be kept secure by using encrypted credential or server-side storage.

Encrypted storage is essential to avoid cross-site scripting (XSS) attacks.

Token Durations

Token durations are set by the data provider.

The ID token is a short-term token used for requesting data through the Data Access API.

Refresh an expired ID tokenRefresh an expired ID token

Refresh an expired ID token

The end-user’s long-term authorization is tied to the refresh token. Refresh tokens are used to request a new set of refresh and ID tokens.

Refresh tokens may be perpetual or some providers may have a set expiration. In the case a provider may set expiration dates for refresh tokens, implementing refresh token rotation is recommended. See specific data provider documentation for their token durations. In Sandbox, the token durations are set as below:

Sandbox token durations

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

If a token expires, Akoya returns an error. For more on these errors, see:

ID token

The Akoya ID token is an identifier for the end-user. It is a short-lived token. This token is used with each call to the Data Access API.

A recommended approach on how to refresh the ID token is described in Recommended use of refresh token with Data Access calls.

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

If you make a call with an expired ID token, you will receive a 602 error.

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

The Token API allows you to rotate tokens using the current refresh token to request a new set of ID and refresh tokens.

Expired ID tokenExpired ID token

Expired ID token

After receiving a new set of tokens, use the new ID token for your data request.

Refresh token

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

The refresh token must be treated as highly confidential.

Refresh tokens are encoded and longer-lived than ID tokens. Refresh tokens are used with the Token API and not with the Data Access API. A call to the Token API to refresh tokens issues new ID and refresh tokens. This refresh token rotation protects applications from token compromise.

Some data providers set an expiration time for refresh tokens so that a user must reaffirm they want to share their data. Commonly, this expiration date is set to a year after authorization. If a refresh token expires, linking the new refresh token with the end-user requires matching the sub value in the ID token's JWT claims.

Recommended use of refresh token with Data Access calls:

The ID token contains the exp JWT claim (see above). Check the expiration before each data call. If the ID token has expired, make a refresh token call before the call to the Data Access API.

Refresh token error

In the case of a provider setting an expiration for refresh tokens, 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 (see: Authorization steps).

A possible token flow if both ID and refresh tokens are expiredA possible token flow if both ID and refresh tokens are expired

A possible token flow if both ID and refresh tokens are expired