# 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`](/docs/api-reference/account-connection-api#start-oauth-account-linking) 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](/docs/account-linking/oauth-authorization-code) | 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](/docs/account-linking/signed-token-callback) | 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](/docs/account-linking/retroactive-events) explains how the Signed Token Callback Flow can include
  qualifying Advertiser events that occurred before the connection was confirmed.
- [Security requirements](/docs/account-linking/security-requirements) covers backend-only calls, token handling,
  redirects, OAuth secrets, and common impersonation risks.
- The [public API reference](/docs/api-reference/account-connection-api) contains the exact current request and response
  schemas.