SynqDocs
Guides

Migrating to Synq

Move your users in from another provider, such as Auth0, Clerk or Firebase, or your own database. Make each one through the management API, switch your apps over, and know what each person sees at their first sign-in.

Whether your users are in Auth0, Clerk, Firebase or your own database, the move works the same way: export them, make each one at your brand through the management API with their email address, then point your apps at your brand's issuer. Nobody makes a new account. Each person signs in with the same address, and the ways they used before join their account as they use them.

Some things don't come across today: password hashes, your own user ids as Synq's ids, people's Google and other provider accounts and their wallets attached ahead of time, and people who signed in with a wallet alone. What doesn't come across yet says what each means for your users.

What you can bring

Make a user takes:

FieldWhat to put in it
emailTheir email address, which they sign in with. Every user you make needs one
email_verifiedtrue when your current provider says they proved the address. false (the default) when it doesn't: their first emailed code proves it
username, name, given_name, family_name, picture, localeTheir profile. A username is 3 to 64 lowercase letters, digits and . _ -, starting and ending with a letter or digit; a picture is an https URL; a locale is a BCP 47 tag
metadataUp to 16 KB of your own JSON: their id at your current provider, say, and anything else your apps keep about them

The answer is the new user, whose id (usr_…) is the sub your apps get from then on. Making a user emails them nothing, and doesn't count them as active: a user counts once they get tokens in a month (plans and usage).

Before you start

  1. Pick the brand your users sign in to, and turn on the ways they signed in with before on its sign-in page. A new brand has the email address on, with an emailed code and a password, and a Solana wallet, but every provider, Google included, off.
  2. Choose whose app signs in at each provider. By default it's Synq's own, so Google's page names Synq. To keep the page your users know, give Synq the app you use today at the provider, after adding your brand's redirect URI to it (your own apps at the providers, Pro and up).
  3. Make an API key that can make users, one with org.users.edit in the brand (your first API key). In the dashboard's New API key, under Where it works, keep Brands you choose and give the brand the role Support, which makes, finds and changes its users and changes no settings (Brand admin can too, with everything else in the brand). Or, as the org's owner, pick Every brand and tick Users, View and Change. The form's default role, Developer, can't make users: the script's every user would be refused with insufficient_permissions.

Making your users

Export your users from your current provider, then make each one. $SYNQ_API here is the management API, https://api.synq.build, $SYNQ_API_KEY the key, and $ORG and $BRAND your org's and brand's ids (org_… and brd_…):

curl -X POST "$SYNQ_API/v1/orgs/$ORG/brands/$BRAND/users" \
  -H "Authorization: Bearer $SYNQ_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: import-user-8f2c41" \
  -d '{
    "email": "riley@example.com",
    "email_verified": true,
    "name": "Riley Chen",
    "metadata": { "previous_id": "user-8f2c41" }
  }'

For a whole export, a script makes each user in turn. This one runs on Node.js 22 or later, reads a JSON array of your users, and writes the map from each old id to the Synq id, for your own database. People with no email address, such as those who signed in with a wallet alone, can't be made yet, so it lists them apart in no-email.json rather than among real errors (Solana wallets says how they come across). Each provider's export names its fields its own way, so change toSynq to read yours:

import-users.mjs
// node import-users.mjs users.json
import { readFile, writeFile } from 'node:fs/promises'

const { SYNQ_API, SYNQ_API_KEY, ORG, BRAND } = process.env
const people = JSON.parse(await readFile(process.argv[2], 'utf8'))

// Your export's fields, as Synq's: change this to match your export.
const toSynq = (person) => ({
  email: person.email,
  email_verified: person.email_verified === true,
  ...(person.name ? { name: person.name } : {}),
  metadata: { previous_id: person.id },
})

async function makeUser(body, key) {
  for (;;) {
    const answer = await fetch(`${SYNQ_API}/v1/orgs/${ORG}/brands/${BRAND}/users`, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${SYNQ_API_KEY}`,
        'Content-Type': 'application/json',
        // The same key for the same person, so running the script again makes nobody twice.
        'Idempotency-Key': key,
      },
      body: JSON.stringify(body),
    })
    if (answer.status !== 429) return { status: answer.status, body: await answer.json() }
    // Over the key's rate limit: wait as long as Synq says, then try again.
    const seconds = Number(answer.headers.get('retry-after') ?? '1')
    await new Promise((resolve) => setTimeout(resolve, seconds * 1000))
  }
}

const ids = []
const noEmail = []
for (const person of people) {
  // No address to make them with: their first sign-in makes them. Kept apart, never an error.
  if (!toSynq(person).email) {
    noEmail.push({ previous_id: person.id })
    continue
  }
  const { status, body } = await makeUser(toSynq(person), `import-${person.id}`)
  if (status === 201) ids.push({ previous_id: person.id, synq_id: body.id })
  else if (status === 409) console.log(`${person.email}: ${body.detail} Skipped.`)
  else console.error(`${person.email}: ${status} ${body.code}`, body.errors ?? '')
}
await writeFile('synq-ids.json', JSON.stringify(ids, null, 2))
await writeFile('no-email.json', JSON.stringify(noEmail, null, 2))
console.log(`${ids.length} made; ${noEmail.length} with no email address, in no-email.json`)

What the answers mean:

  • 201: made. Keep the id with your own records of the person, so your apps find them by the sub Synq gives them.
  • 409 with conflict: someone at the brand already signs in with that address, made by an earlier run or signed up themselves. Find them with List a brand's users and ?q= the address. With username_taken, another user has the username: make them again without it.
  • 400 with validation_failed: a field that won't do, such as a username with capitals or a picture on http, named by its pointer. Someone with no email address never gets here: the script lists them in no-email.json.
  • 429: one key makes up to 600 management API requests a minute (rate limits); the script waits the Retry-After and goes on.

Running the script again is safe: within 24 hours the same Idempotency-Key with the same body answers the first answer again (with another body, it's idempotency_key_conflict), and after that a user already made answers 409.

Switching over

  1. Make your users with the script above.
  2. Try a few before you switch anything: make some test users and sign in as each kind, with an emailed code, with Google and with a wallet, at your brand's sign-in page. What each person sees says what to expect. To try Google joining a user you made, turn Google on for the brand first (step 1 of Before you start), make a user with an address you can sign in to Google with, such as your own Gmail address, and email_verified: true, then Continue with Google as that account. A test sign-in can't stand in for it: its address is never verified at Synq and never joins another account, so only a real Google account shows the join.
  3. Tell your users what changes, before the day: people who used a password sign in with a code Synq emails them or set a new password, and people with a passkey make a new one.
  4. Point your apps at your brand's issuer. They keep their OpenID Connect library and change its issuer, client id and secret to your brand's and its app's at Synq (Getting started). Every new sign-in goes to Synq from then on.
  5. Make anyone who signed up since your export: run the script again on a new export. Everyone made before answers 409 and is left as they are.
  6. Run both while the old sessions last. People signed in to your apps through your current provider stay signed in for as long as your apps accept those sessions: Synq never sees or ends them. When one ends, that person signs in through Synq.
  7. Turn your current provider off once your apps no longer accept a session from it.

What each person sees at their first sign-in

They signed in withAt their first sign-in at Synq
An emailed code or linkNothing new: a code to the same address signs them in
A passwordTheir old password doesn't work, since Synq has no copy of it. They sign in with an emailed code, or set a new password (passwords)
Google, Apple or MicrosoftTheir address joins them to the user you made, or the page asks them to sign in to it once (Google, Apple and Microsoft)
GitHub, X, Discord, Facebook, Telegram, MatricaThey sign in to the user you made once, another way, then add the provider (other providers)
A Solana walletThey sign in with an emailed code, then add the wallet. A wallet with no email address behind it is a new user (Solana wallets)
A passkeyThey sign in another way, then make a new passkey (passkeys and second factors)

Passwords

Synq doesn't take another system's password hashes today, so a user you make has no password at Synq. The sign-in page leads with the emailed code after the address by default, which signs them in. Someone who would rather keep a password sets one with "Forgot your password, or never set one?" on the password step: Synq emails a single-use link, good for 30 minutes, which says the account has no password yet, and the password they choose there is theirs from then on. It also verifies their address (setting or resetting a password). Their old password, typed at Synq, signs nobody in: the page says the address and password don't match, and that someone who never set a password here can email themselves a sign-in code or set one. It says the same for every address, so it never tells anyone who has an account here (people with no password).

Google, Apple and Microsoft

Turn Google on for the brand first: it's off on a new brand. Then whether someone's Google account joins the user you made depends on whether Google vouches for the address:

  • Gmail addresses, and a Google Workspace account's address on its own Workspace domain: Google vouches for them. With the brand's link_by_email on (the default) and the user made with email_verified: true, their first Continue with Google signs in to the user you made and adds Google to their account. Nothing else is asked.
  • Any other Google account, such as a personal Google account made with a work address: Google doesn't vouch for the address, so the page says You already have an account and asks them to sign in to it the way they did before, with an emailed code say. Google then joins their account. Create a separate account is offered too, which gets a second user whose address isn't verified. Keep the brand's existing_account_prompt on (the default) while you move: it's what offers them their account (preventing duplicate accounts).
  • An address that isn't proved yet, on a user made with email_verified: false: no provider's sign-in joins that user until the address is proved. They sign in with an emailed code first, which proves it. So make a user with email_verified: true whenever your current provider says the address is proved.

Apple vouches for its own mailboxes and Microsoft only with its xms_edov claim (social accounts). An Apple private relay address never joins another account by email, so someone who hid their address from Apple signs in with an emailed code first, then adds Apple.

Other providers

GitHub, X, Discord, Facebook, Telegram and Matrica never vouch for an address. A sign-in with one that brings an address another user proved gets You already have an account, as above. One that brings no address (Telegram always, and X or Discord when they give none) asks New to Acme? first: I have an account: sign in another way takes them back to the sign-in page, where an emailed code signs them in to the user you made. They then add the provider from their account (adding and removing ways to sign in).

Solana wallets

Make a user needs an email address, and you can't attach a wallet to someone you make. So:

  • People who had an address at your current provider are made with it. They sign in with an emailed code, then add their wallet from their account. Someone who signs in with the wallet first gets a new account that holds only the wallet; when they then add the wallet to the account you made, that empty account merges into it at once (merge_empty_accounts, on by default), and your webhooks get user.merged with the old sub and the new (merging empty accounts).
  • People who signed in with a wallet alone, with no address, can't be made today: the import script lists them in no-email.json. Their first sign-in with the wallet makes a new user. Match them to your records by the wallet's address: a brand's own app with sign_in_claims on gets it as sign_in_wallet in the ID token (sign-in context), and your server reads a user's wallets with Read a user.

Passkeys and second factors

A passkey belongs to the host it was made on, and its private key never leaves the person's device, so no passkey moves from any provider to another. People sign in another way, then make a new passkey at Synq (passkeys).

Synq has no codes from an authenticator app (TOTP) and none by text message. A passkey counts as two factors on its own, and your app can ask for one before something sensitive (insisting on a passkey).

What doesn't come across yet

  • Password hashes. Synq doesn't take another system's hashes today. People sign in with an emailed code, or set a new password.
  • Your own user ids. Every user's sub is Synq's (usr_…). Keep your old id in metadata, and the Synq id with your own records.
  • Provider accounts and wallets, ahead of time. You can't attach someone's Google account or wallet when you make them. Provider accounts and wallets join as people use them, as above.
  • People with only a wallet. Make a user needs an email address, so someone who signed in with a wallet alone can't be made: their first sign-in with the wallet makes a new user (Solana wallets).
  • Sessions. Everyone signs in once at Synq, when their session with your current provider ends.

A bulk import that brings password hashes, your own user ids, people's provider accounts and wallets, and people with only a wallet is coming later. There's no date for it yet.

Leaving works the other way round: Leaving Synq says what an export gives you.

On this page