Account Linking

Account linking ties a customer’s accounts on two sister sites together so that data (such as loyalty) and authentication can flow between them. The flow is a three-step token exchange that has to happen while the customer is logged into each account in turn — the API never sees both sets of credentials at once.

All linking operations require authentication and the ACCOUNT_LINKING site feature.

Listing linked sites

Use this on the account section of a site to show which other sites the customer has linked.

query SiteLinks {
  siteLinks {
    name
    site
    url
  }
}

The three-step linking flow

The flow involves the customer being logged into both the origin (the account they want to link from) and the target (the account they want to link to). The site running the UI orchestrates the token hand-off — typically by redirecting the customer between the two sites with the token in the URL.

Step 1 — On the origin site, request a linking token

The customer is logged into the origin account. The token returned identifies the origin account and is what authorises the link.

mutation GetAccountLinkingToken {
  getAccountLinkingToken {
    error
    accountLinkingToken
  }
}

The customer is then sent to the target site, carrying the accountLinkingToken.

Step 2 — On the target site, exchange for an extension token

The customer is now logged into the target account. Show them what’s about to happen first by calling accountLinkingTokenInfo with the token, which reveals the origin email so the customer can confirm they recognise it.

query AccountLinkingTokenInfo {
  accountLinkingTokenInfo(accountLinkingToken: "link_abc...") {
    error
    email
  }
}

If the customer accepts, exchange the linking token for an extension token. The extension token is returned to the origin site to complete the link.

mutation GetAccountExtensionToken {
  getAccountExtensionToken(
    input: { accountLinkingToken: "link_abc..." }
  ) {
    error
    accountExtensionToken
  }
}

The customer is then sent back to the origin site with the accountExtensionToken.

Step 3 — Back on the origin site, complete the link

mutation LinkAccounts {
  linkAccounts(
    input: { accountExtensionToken: "ext_def..." }
  ) {
    error
    email
  }
}

Unlinking

unlinkAccount removes the link to a single specific site by code; unlinkAccounts removes all links from the current account.

mutation UnlinkAccount {
  unlinkAccount(targetSiteCode: "lfint")
}

mutation UnlinkAccounts {
  unlinkAccounts
}