Token Overview

This guide provides an overview of the authentication and authorization process. It also explains the two types of tokens and covers some or our best practices.

Authentication & authorization

For you to connect your consumer’s data to your app, the consumer must authenticate with the data provider and authorize data to be shared. Initial authentication remains in effect until either the consumer revokes access to their data or their associated refresh token expires. Akoya uses an OAuth 2.0 flow with OpenID Connect (OIDC) authentication protocol.

Authorization Endpoint

Your app sends the consumer to Akoya’s login page using a specific URL with required parameters for authentication. On success, an authorization code is granted to your app.

Find more details in Get authorization code.

The consumer completes the authorization consent with the data provider. At this point, Akoya sends the consumer to your app’s redirect_uri with the authorization code and state.

HTTP/1.1 302 Found
Location: {Your redirect URI as specified in the authorization endpoint}
 ?code={Authorization Code} // - Code valid for 5 minutes to be exchanged for token
 &state={Arbitrary String} // - String matching the state provided in the authorization endpoint

To prevent possible CSRF attacks you should validate your state param. You can find more information about this important security step here: https://auth0.com/docs/secure/attack-protection/state-parameters

Example URL sent to your app with authorization code: /flow/callback?code=vhmji7kmopeil4jyb57wc4znx&state=

Authorization Code for Token Exchange

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 consumer’s data.

curl -X POST https://sandbox-idp.ddp.akoya.com/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code={Authorization Code}" \
  -d "redirect_uri={Redirect URI}"

Success Response:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "expires_in": 86399,
    "grant_id": "7a85456e-4e1a-46d9-b1bf-4fa2792baee5",
    "id_token":<<idToken JWT>>,
    "refresh_token": <<Refresh Token>>,
    "token_type": "bearer"
}

Should an error occur, please consult the token error documentation here.

ID Token

Akoya will issue your app an ID token (OIDC token—a signed JSON Web Token). The ID Token is a short-term token used for requesting data from Akoya endpoints.

This means the ID token will function as your access (bearer) token. The /token endpoint will not return an explicit field called access_token. This is called out as some libraries and tools may need adjustments or won't handle this correctly out of the box. For example, Postman currently expects there to be an explicit field access_token field for the built in OAuth2.0 generic handler. In the Akoya postman collection, this will be handled for you. Once the token is created using the environment file and test code, the id_token is set to be used in all the requests as the bearer token for the authorization header.

Tokens are granted for each consumer for your specific app and are specific to their current account authorization. Please see the unique keys and values guide for specifics as to the level of specificity of the token and elements. This token may be decoded to view identity token claims (see ID token details) which may be helpful in more advanced usage scenarios.

The ID token lifetime has a 24 hour maximum. However, providers often have a shorter expiration for ID tokens.

Make a refresh token call to renew the tokens if they expire or after an app uses an ID token for 15 minutes to follow this recommendation.

Refresh Token

The refresh token is a longer-term token and is tied to the consumer’s authorization. Refreshing tokens allows your app to replace an expired ID token without asking the consumer to reauthenticate and maintains authorization when the consumer is not actively using your app. The refresh token is not a JWT token and thus, cannot be decoded.

Refresh tokens are used with the Token API and not as bearer tokens in Akoya endpoint calls. A call to the Token API to refresh tokens issues a new ID token and also a new refresh token. Make sure to store the new refresh token from the refresh call. You need the new refresh token to make the next refresh token call successfully.

Refresh token lifetime

Refresh tokens have a set expiration of one year from the date of authorization. After expiration, reauthentication is forced. The consumer is required to go through the consent flow again regardless of any token activity. The UX best practice is to code proper error handling as tokens may expire earlier than the stated expiration times.

Token usage best practice

The above diagram shows the two levels where tokens can fail and how to proceed. The first level is failure during a data request, in this case /accounts. The second level is when trying to refresh the ID token (the refresh token has expired).

Expired ID Token

If an app requests data through an Akoya endpoint using an expired ID token, the app will receive a 602 error. During this scenario, the token may or may not be past the expiration time. It may even have just been used; however, an event occurred where the ID token is no longer valid. Any data request with an expired token will result in the follow error:

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

To best handle this, Akoya recommends using a generic wrapper around all data calls that specifically looks for the 602. Upon receiving this error, the app should send a refresh token request to the Token API and then try the data request again with the updated ID Token returning the data to the initial data call.

Expired refresh token

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 consumer back through the consent flow and account selection process to reauthorize and receive a new set of ID and refresh tokens.

This helps the user understand they are going to need to go through the consent flow. Upon completion, you can present a call-to-action to resume the previous activity. This approach helps you because you don’t need to pause the current state. You just need an indicator of where to direct the user once done. This is common industry behavior that your users should be accustomed to.

Stop the never ending refresh loop

Once you receive an invalid request error indicating the refresh token is no longer valid, we recommended you flag the link as broken and stop attempting to refresh. This will prevent unnecessary noise in your error logs if you are running batch processes.

When a token is deemed broken, the only way to correct it is to have the user go through the consent flow again.

More information on consent flow/token standards

To support authorization and ensure data privacy, Akoya uses tokens to verify consumer 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.

Change log