Update Mode

​

When to use update mode

Update mode refers to any Link session launched for an account that has already been linked. Update mode is used when an existing account linkage requires input from a user, such as to update credentials.

One common use of update mode is to update authentication or authorization for a linked account. This can be required when access to an existing account stops working: if the end user changes a password, if multi-factor authentication (MFA) requirements change, or if the login becomes locked.

​

Resolving login_required errors

Receiving an login_required error or a login_required webhook indicates that the account should be re-initialized via update mode.

Example 403 login_required response:

{
    "success": false,
    "error": "login_required",
    "message": "Account link expired. Please go through the integration setup again."
}

If you receive the login_required error after calling a Cobalt endpoint, implement Link in update mode during the user flow, and ask the user to re-authenticate before proceeding to the next step in your flow.

If you receive the login_required error in an API call response, or if you receive the login_required webhook, re-authenticate with Link in update mode when the user is next in your app. You will need to tell your user (using in-app messaging and/or notifications such as email or text message) to return to your app to fix their Item.

When resolving these errors, Cobalt will present an abbreviated re-authentication flow requesting only the minimum user input required. For example, if the account entered an error state because the user’s OTP token expired, the user may be prompted to provide another OTP token, but not to fully re-login to their account.

​

Using update mode

To use update mode for an Item, initialize Link with a link_token configured with the access_token for the account that you wish to update.

curl -X POST https://api.usecobalt.com/link/token/create \
-H 'Content-Type: application/json' \
-H 'client_id: "%COBALT_CLIENT_ID%"' \
-H 'client_secret: "%COBALT_CLIENT_SECRET%"' \
-d '{
  "user_id": "%REFERENCE_USER_ID%",
  "org_id": "%REFERENCE_ORG_ID%",
  "access_token": "%EXISTING_ACCESS_TOKEN%"
}'

Link auto-detects the appropriate EHR and handles the credential and multi-factor authentication process, if needed.

An account’s access_token does not change when using Link in update mode, so there is no need to repeat the exchange token process.