Advanced token scenarios

This guide discusses more advanced token scenarios and how you could handle them.

Updating tokens

When the user goes through the consent flow again you’ll receive a new ID and refresh token. However, as the user is going through the consent flow again, there are two key scenarios you should be aware of:

• Some providers allow the user to change the scope of data shared. For instance, if the user had previously elected to share statements but opted out of sharing statements this time through consent, your application should handle this.

Providers also generally allow the user to change the accounts that are shared You should expect to see new/less/different accounts after a reconsent and populate your UX accordingly.

Scenario: Users may accidentally log into a different account than previously linked

In this scenario, a user may have multiple logins to a single provider. The first time they use your app, they may use login 1 (personal account) and during reconsent may forget and use login 2 (business account). Your app will see a whole new set of accounts. This can create confusion in your UX depending on how you handle it.

When sending a user through reconsent, take note of the current ID token. If you inspect it, you’ll see the sub claim. Once you’re granted the new ID token, you can inspect it and compare the values. We recommend at the very least at least alerting the user they are about to link a new set of accounts and will render the previously linked accounts no longer accessible.

Updating shared accounts/scopes

There are two ways a user can update the accounts and scope of data that is shared:

• Some providers offer a page on their logged in site, usually under security settings, where the user can see the accounts and data that shared with apps. Some providers offer the ability to change current settings, while some simply offer a revoke token option.
• The second way is from the app where you would guide the user to go through the consent flow again to update the selected accounts and scopes. At this point, you’d also be issued new ID and refresh tokens.

As your app will not necessarily be notified of these changes, Akoya recommends checking the /accounts-info endpoint after all reconsents, and to code with a general handler that will check for expired/revoked tokens. See token usage best practices.

Identifying the user

You can inspect the ID token as it’s a JWT with various claims. See ID token details for more info. In the claims, you’ll see the sub claim. This claim is the best and only guaranteed way to uniquely identify a user in your app. This claim will persist between refreshes and reconsents within the context of your app. You will not be able to identify the same user across multiple apps or multiple providers.

Should your use case necessitate, the best way is to have the user link their providers then call the /customer product and compare the datasets.

Prompting before expiration

In certain cases, like batch processing/daily aggregation of user information, you may wish to prompt your users to reauthenticate before the token expires to provide a more seamless experience. You can see each provider’s refresh policy timeline in the Data Recipient Hub.

📘

Note

This is a great opportunity to create an email/notification touchpoint to reengage less active users.

Handling multiple logins for single user

Users can have logins for multiple providers and multiple logins per provider, so unless your application restricts the user to only one connection, the recommended approach is to have a data structure similar to the following:

{
	"provider1": {"links": [
		{
			"token": "abcdefg",
			"sub": "xyz123",
			"accounts": ["abc123","def456"]
		},
		{
			"token": "hijklmno",
			"sub": "uvw456",
			"accounts": ["ghi789","jkl012"]
		}
	]},
	"provider2": {"links": [
......

Note the use of the sub claim. This will allow you to keep the connections separate without duplicating.

Also, allowing for some sort of user input nickname per link can be useful. When prompted to re-link, the user will likely remember which login they used.

Multi session/token handling

In some scenarios, you may have different parts of the system working with user data from the same link in multiple places at the same time. The nature of the static refresh token will allow you to have multiple active ID tokens at any given time.

🚧

Note

Akoya recommends handling consent flow and updates to the refresh token in a centralized part of the distributed system to avoid conflicts in your code.

Should a token expire in one part, you should be able to refresh without causing issues with the other tokens. If the refresh token expires and you need to send the user through the consent flow again, you will see disruption across tokens as any existing ID Tokens will stop working.

A user can have multiple active sessions; however, they can only have a single link in your application per provider login.

It’s important to note that even if you have two users in your system, if the same provider is used by both “users” only one link will be active. For instance, user1 links provider X, then user2 uses the same credentials to link provider X. The token saved for user1 will no longer be valid. If you find you’re encountering this issue you may wish to validate against the sub claim to inform your active user they have linked a provider effectively unlinking it from a different account. See Identifying the user for more information on using this claim.

Change log

Need help?

Check out our Developer Community, or visit the Support Center in the Data Recipient Hub.

Looking for provider nuance documentation?

All provider nuance documentation is available in the Data providers section in the Data Recipient Hub.

Still stuck?

For all production issues, submit a support ticket through the Data Recipient Hub. Our support team is standing by 24/7. Questions and non-production issues will be answered during business hours.