Advanced Token Scenarios

This guide covers how to handle advanced token scenarios.

Updating tokens

When the user goes through the consent flow again, you receive a new ID and refresh token. There are two key scenarios you should be aware of in this situation:

• Some providers allow the user to change the scope of data shared. For example, if the user originally elects to share statements but opts out of sharing statements during a later consent. Your application needs to be able to handle the change of scope from an existing user.

• Providers also generally allow the user to change the specific shared accounts. Your application needs to be able to handle the addition or removal of specified accounts from an existing user. The UX should populate 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 a login for a personal account. During reconsent, they may incorrectly use their business account login. The incorrect login with the business account presents your app a different set of accounts. You can design your UX to handle an improper login. When sending a user through reconsent, take note of the current ID token. Inspect it for the sub claim. Once you’re granted the new ID token, you can inspect it and compare the values. We recommend alerting the user, when they are about to link a new set of accounts. Let them know it will render the previously linked accounts no longer accessible.

Updating shared accounts/scopes

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

• Providers offer users a web page to see the accounts and data they share with apps. This page requires a login and is often located under security settings. This page may offer users the ability to update current settings or the option to revoke the consent token.

• Providers let users update through the app. The user is guided through the consent flow again to update the selected accounts and scopes. The provider issues new ID and refresh tokens after the update.

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

Identifying the user

The ID token is a JSON Web Token (JWT ) with various claims. For more information, see ID token details. You can inspect the claims and see the sub claim. This claim is the best and only guaranteed way to uniquely identify a user in your app. This claim persists between refreshes and reconsents within the context of your app. You cannot 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. You can then call the /customer endpoint and compare the datasets.

Prompting before expiration

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

Handling multiple logins for single user

Users can have logins for multiple providers and multiple logins per provider.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": [
......

The use of the sub claim allows you to keep the connections separate without duplicating.

You can also allow a user to nickname their link. When prompted to re-link, the user is more likely to remember the link with a nickname.

Multi session/token handling

You may have different parts of your system working with user data from the same link in multiple places at the same time. The nature of the static refresh token allows you to have multiple active ID tokens at any given time.

A token expiration in one segment should not cause refresh issues for 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. 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 is 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. Then inform your active user they have linked a provider, which unlinks the provider from a different account. See Identifying the user for more information on using this claim.

Change log