Adding and removing ways to sign in

A person can hold several ways to sign in (up to 20): an email address, passkeys, wallets and accounts at the providers the brand offers. One of the brand's own apps lets them add and remove them through the account API, with an access token for it (me:read, me:write).

Adding oneCopy Anchor Link

1. Ask for a link request. POST /me/v1/link-requests on the brand's issuer, with the method to add: wallet, email, google, github, microsoft, apple, facebook, x or discord. It answers the request's expires_at (10 minutes) and authorization_params.
2. Send the person to sign in from the same app, with its own PKCE, state and redirect URI, adding the authorization_params: prompt=login, synq_intent=link and synq_link.
3. They sign in again as themselves, with a way they already have. Anyone else, or someone new, is refused before anything changes: a session someone left signed in proves nothing. It's a fresh sign-in, so a provider that can't show one (Apple, Facebook, X, Discord, Telegram) isn't offered, except to an account whose ways in are all such providers: it signs in again with its own, as a sign-in whose time Synq can't prove, so it can add a way in that can show one. An account with an address it proved can use an emailed code to that address instead.
4. They use the method being added: their wallet signs, an emailed code proves the address, or the provider signs them in. It joins their account (user.identity_linked), and the sign-in finishes as theirs.

The link request authorizes nothing by itself: it works only for that person, through that app, with that sign-in in the browser. "Not now" finishes the sign-in without adding anything.

With @synqauth/nextjs, the app's own route mount does the first two steps: POST { method, returnTo } as JSON to /api/auth/link from your pages and send the browser to the redirect it answers, or call useAuth().link('google') from @synqauth/react. See the Next.js guide.

What can't be added:

• an identity another user has: refused, never merged, and the person can try another
• an email address, for an account that has one, or that another user verified
• a method the brand doesn't offer, or a provider that can't show a fresh sign-in (GitHub, Apple, Facebook, X and Discord): sign_in_method_unavailable
• anything past 20 ways to sign in: identity_limit_reached
• anything, while the account's email address is unverified: email_unverified, until the person verifies it

A sign-in proved before every session of the user ended (a password reset, say) adds nothing. Passkeys are added on their own: see passkeys.

Listing and removingCopy Anchor Link

List the person's ways to sign in (passkeys are their own list), and remove one, which needs a sign-in from the last 5 minutes whose time Synq proved (fresh_sign_in_required otherwise). The last way to sign in can never be removed (last_sign_in_method). Removing it doesn't end the sessions it signed in: end them too if you should.

Removing the email address removes its password with it. The address stays the person's contact address but is no longer verified, so no provider's word links anyone to the account through it.