Skip to content

Connect a provider to an existing account

Target Audience: Developers, Stakeholders

Introduced in Payway 4.10.

Let a signed-in user link a Google / Microsoft / Apple account to their existing Payway account — so next time they can sign in with that provider. This is the "connected logins" action in an account / settings screen. It never creates or switches accounts: the link is always made to the account behind the user's own access token, never to an identity passed in a parameter.

Prerequisites

  • The user is signed in and you hold their access token with scope /external/me/social/w.
  • Your app can run the provider sign-in (same native OAuth client + native-audience setup as Sign in in a native app).

Flow

  1. Request a nonce — POST {sso}/social/{provider}/native/nonce (client-auth JWT) → { nonce }.
  2. Run the provider sign-in in your app with that nonce → obtain the provider id_token.
  3. Attach — POST {payway-api}/external/me/social/attach_native with the user's access token:
{ "provider": "google", "id_token": "<provider id_token>", "nonce": "<nonce from step 1>" }

Payway validates the id_token (JWKS + aud + the nonce), takes the account from your access token (not from the body), and links provider → sub. Response: { "status": "ok", "provider": "google" }.

Errors

Code Meaning
already_linked this account already has that provider linked
identity_in_use that provider identity is already linked to a different account
id_token validation failed the id_token / nonce didn't validate

See also