Token Overview
This guide provides an overview of the authentication and authorization process. It also explains the two types of tokens and covers some 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, the system grants an authorization code 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.
BASH
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: https://recipient.ddp.akoya.com/login/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.
BASH
Success Response:
BASH
Should an error occur, consult the token error documentation here.
ID Token
Akoya issues 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 functions as your access (bearer) token. The /token endpoint does not return an explicit field called access_token. We call this out because 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. The Akoya Postman collection will handle this for you. Once you create the id_token using the environment file and test code, Postman uses it in all the requests as the bearer token for the authorization header.
The system grants tokens per consumer for your specific app, tied to their current account authorization. See the Unique Keys and Values guide for specifics as to the level of specificity of the token and elements. You can decode this token 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 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 and thus you cannot decode it.
The Token API uses refresh tokens to issue 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 may be perpetual, have a rolling expiration, or have a set expiration from the date of authorization. Token expiration times are documented in the Data Recipient Hub. The Akoya UX best practice is to code to proper error handling as tokens may expire earlier than the stated expiration times.
Perpetual
The provider has no set expiration date for the refresh token.
Set expirations
Tokens have a set expiration period that forces reauthentication after the time indicated. This is commonly a year. After the token’s expiration, the consumer needs to go through the consent flow again regardless of any activity using the token.
Rolling expiration
Using the token resets its duration. For instance, if your consumer’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 resets to six months from that time. However, if your app hasn’t refreshed tokens in 6 months, the consumer will need to go through the consent flow again the next time they use your app.
Token Usage Best Practice
This 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 receives a 602 error. During this scenario, the token may or may not be past the expiration time. It may even have recently been used; however, an event occurred where the ID token is no longer valid. Any data request with an expired token results in the follow error:
JSON
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 receive an invalid_request error.
JSON
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 only need an indicator of where to direct the user once done. This is common industry behavior that your users should expect.
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 prevents unnecessary noise in your error logs if you are running batch processes.
When a token breaks, 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.