Copy page

Account linking

Account linking

Account linking lets Onward associate a Platform user with the matching account in an Advertiser system. It is used for tasks such as creating an account, signing in, or proving that an existing Advertiser account belongs to the same user.

The Platform starts the journey, Onward coordinates it, and the Advertiser authenticates or registers the user. The Platform does not need to implement Advertiser-specific linking logic.

When to start account linking

The Platform reads the user's active quest chains and checks the task's condition_event_type. A task with condition_event_type: "link_account" requires an Advertiser account connection.

The Platform backend then calls POST /v1/account/start-connect with:

• the authenticated user's stable platform_user_id;
• the task's quest_chain_id;
• a Platform redirect_url to which the user can return after the flow.

Onward returns a redirect_url ready for the browser. Its destination and contents depend on the Advertiser's configured account-linking mechanism.

Choose a mechanism

Mechanism	How the connection is completed	Best suited to
OAuth 2.0 Authorization Code Flow	The Advertiser issues an authorization code, and Onward exchanges it through the Advertiser's token endpoint.	Advertisers with an existing OAuth 2.0 service.
Signed Token Callback Flow	The Advertiser receives a short-lived Onward token and confirms the connection from its backend.	Advertisers that need a smaller integration surface or do not operate OAuth 2.0.

Both mechanisms give the Platform the same high-level experience: request a connection URL, redirect the user, and receive the user back after Onward has either connected the identities or reported an error.

Shared lifecycle

1. The user starts a task that requires an Advertiser account.
2. The Platform backend verifies the user's identity and asks Onward to start the connection.
3. Onward returns an Advertiser redirect URL.
4. The browser opens the Advertiser's sign-up or sign-in experience.
5. The selected mechanism proves the Advertiser identity to Onward.
6. Onward links the identities and updates matching quest-chain progress.
7. The browser returns to the Platform's registered redirect_url with a success or error result.

Supporting topics

• Retroactive events explains how the Signed Token Callback Flow can include qualifying Advertiser events that occurred before the connection was confirmed.
• Security requirements covers backend-only calls, token handling, redirects, OAuth secrets, and common impersonation risks.
• The public API reference contains the exact current request and response schemas.