docs
  1. Checkout Guide
  2. Authentication & Accounts
  3. Customer Management
  4. Account Linking

Account Linking

Introduction

Account Linking allows users to associate multiple authentication identities—such as traditional email/password credentials and Single Sign-On (SSO) providers like Apple, Google, or Klarna—with a single, unified customer account. This centralization improves customer management, ensures a consistent user experience across platforms, and avoids account fragmentation.

Precautions

Linking accounts without reliable identity verification introduces security risks. Malicious actors could exploit unverified links to gain access to legitimate accounts. Therefore: Only enable account linking if the Identity Provider ensures verified user authentication, such as through email validation.

How it Works

User Identities

At SCAYLE, a customer is represented by a single primary customer account, which may have one or more linked secondary user identities. These identities may originate from different authentication mechanisms (e.g. email/password based or Identity Provider based SSO like Facebook or Apple).

TypeDetails
(Primary) Customer Account
  • Always unique with exactly one customer_id
  • Created via Email/Password or Identity Provider, depending on first successful login
  • Defines the customerObject and holds all core customer data
  • Acts as the root identity to which all other user identities are linked
(Secondary) User Identity
  • Always based on an Identity Provider (e.g., Apple, Google, Klarna)
  • Multiple user_identities can be linked to a single customer_id
  • Does not modify the customerObject of the primary account
  • If the primary account is deleted, all linked secondary user identities are deleted as well

Key Considerations

Account linking at SCAYLE is governed by a set of strict rules to ensure user security and data consistency. The following principles define how identities are linked and when linking is permitted:

AspectDescription
Primary Account DefinitionThe first successfully registered user identity (via email or IDP) becomes the primary customer account, uniquely identified by a customer_id.
Secondary Identity LinkingAdditional user identities (via IDPs) may be linked as secondary identities to an existing primary account.
Linking PreconditionsLinking is only permitted when the system finds a matching external_id (for the same user) or a verified email address associated with an existing primary account.
Order of Creation MattersThe sequence of identity creation is critical. For example, linking a new email-based identity to a previously created, IDP-based account is restricted due to verification differences and security risks. The reverse (linking an IDP to an existing email account) is on the other side allowed.
Identity Origin MattersIDPs typically offer built-in user verification (e.g., Apple or Google email validation), while email/password flows may lack this. Therefore, SCAYLE restricts linking from unverified origins to verified ones.
Admin API LimitationCustomer accounts created via SCAYLE’s Admin API WITH an Identity Provider flag are treated as primary accounts and cannot be linked retrospectively to any previously created email-based account. The Admin API enforces strict uniqueness and non-mergeability of customer records.

Linking Scenarios

When linking occurs, two primary factors determine the outcome:

  • Origin of the primary account (e.g., email/password vs. SSO).
  • Order of user creation.

As described above please consider Linking is asymmetric - A new SSO-based login can be linked to an existing email/password account, but not the other way around, to prevent account takeover without prior user verification.

Simple Linking Cases

CasePrimary AccountSecondary IdentityResult
#1EmailApple SSO✅ Linked
#2Apple SSOFacebook SSO✅ Linked
#3Apple SSOEmail❌ Not possible

Advanced Linking Cases

CasePrimary AccountSecondary 1Secondary 2Result
#5EmailApple SSOFacebook SSO✅ Linked
#6Apple SSOEmailFacebook SSO⚠️ Partially Linked: E-Mail account stays independed
#7Apple SSOFacebook SSOEmail⚠️ Partially Linked: E-Mail account stays independed

Scope & Limitations

Linking Options

Linking OptionDescriptionStatus
Link IDP to Primary Email AccountNew IDP login links to existing email-based customer✅ Implemented
Link Email to Primary IDP AccountNew email-based login links to existing IDP customer❌ Not supported
Multi-IDP LinkingMultiple IDPs linked to one primary account✅ Supported

Capabilities

FeatureDescription
Revert configurationsIf account linking is later disabled via configuration, newly created user identities will no longer be linked to existing customer accounts. Note that any previously established links remain intact and cannot be undone.
Unified user data and order history across identities.If user identity was linked to one existing customer account, the order history of the primary account will be shared despite the login
Token revocation across linked accounts.Token revocation and customer deletion are always performed based on the customer_id. If multiple identities are linked to the same customer_id, all associated records will be deleted accordingly.

Limitations

FeatureDescription
Merging existing user accountsNew IDP login links to existing email-based customer
Unlinking accountsNew email-based login links to existing IDP customer

Feature Set

AreaBehavior
Reset/Change Password
  • Only possible for accounts created by E-Mail.
Change Email Address
  • Only possible for accounts created by E-Mail.
Change Personal Info
  • Only possible for accounts created by E-Mail.
Update Notifications
  • Relies on primary account and given E-Mail address.
Change IDP Email Externally
  • SCAYLE will not update the respective user or customer records while ensures that no new user record is created.
Show Order History
  • Shared across linked accounts.
Customer Deletion
  • Customer deletion in Auth affects all linked records connected to one customer_id.
Revoke Tokens
  • Token revocation is done on a user level.
  • If a bulk access token revocation is performed, it will affect all records connected to one customer_id.

Question & Answer

  • Q: Why can I not merge an SSO-based primary account to a secondary email account?
    A: To prevent account takeover, linking is allowed only from new IDP accounts to existing email accounts - not vice versa.\
  • Q: Can emails and passwords still be updated after linking?
    A: Yes. Updates apply to the primary account (only for E-Mail based records), and linked identities remain valid.\
  • Q: What happens if the email is changed on the IDP side?
    A: If the IDP updates the email, matching will fall back to external user ID
  • Q: Do I need to anonymize all user identities when using SCAYLE’s anonymization feature?
    A: No. Since linked user identities are connected via. customer_id to the the primary customer record all records for a given customer_id will be anonymized automatically to comply with data privacy regulations