Upgrading the SDK
What behaves differently when you move an app from @synqauth 0.4 to 0.7, what to set to keep the old behavior, what 0.8 brings, and how a Next.js app builds with Cache Components.
The @synqauth/* packages share one version and move together, so upgrade every one your app uses to the same version at once. They're at 0.x, so a minor release can change how something behaves. This page lists what an upgrader must know, with the version each change came in. The SDK changelog has every change, and the API and MCP changelog every change to the APIs the packages call.
Install the version you're moving to, named, rather than @latest, which is whatever npm has newest as you run it. To move a Next.js app to 0.8.0:
npm install @synqauth/nextjs@0.8.0Add only the packages your app already uses, each at that same version: @synqauth/react@0.8.0 if it imports @synqauth/react, and @synqauth/js@0.8.0 if it imports @synqauth/js itself. Each package also ships its CHANGELOG.md.
Which versions are on npm
- 0.4.0, 8 November 2026.
- 0.5.0 never went to npm. Its changes came out in 0.6.0, so the changelog's 0.5.0 entries are part of the upgrade.
- 0.6.0 and 0.7.0, both 15 November 2026.
- 0.8.0, the next after 0.7.0: From 0.7 to 0.8 lists what it brings.
Before you start
A web app's redirect URIs are https, on localhost too. Only a native app may use http://localhost. If your app's .env.local has SYNQ_APP_URL=http://localhost:3000, serve it over https and register its https addresses on your development app:
SYNQ_APP_URL=https://localhost:3000 next dev --experimental-httpsRegister https://localhost:3000/api/auth/callback and https://localhost:3000/ under Where people come back. The dashboard refuses an http:// address there as soon as you add it. Developing on your laptop has the rest.
Cache Components
If your next.config.ts has cacheComponents: true, as create-next-app 16 writes it for a new app, a page that awaits synq.me(), synq.getSession() or synq.getAccessToken() at its top level doesn't build, on any version:
Error: Route "/": Next.js encountered uncached or runtime data during prerendering.They read the request, and Next prerenders a page at build time, all but what sits inside <Suspense>. Move each read into a component of its own inside a boundary. This page, as 0.4's readme set it up, doesn't build:
import { synq } from '@/lib/synq'
export default async function Home() {
const me = await synq.me()
return (
<main>
{me ? (
<a href="/dashboard">Go to your dashboard</a>
) : (
<a href={synq.signInPath({ returnTo: '/dashboard' })}>Sign in</a>
)}
</main>
)
}It builds once it reads the session inside <Suspense>:
import { Suspense } from 'react'
import { synq } from '@/lib/synq'
export default function Home() {
return (
<main>
<Suspense fallback={<p>Checking who is signed in…</p>}>
<Links />
</Suspense>
</main>
)
}
async function Links() {
const me = await synq.me()
return me ? (
<a href="/dashboard">Go to your dashboard</a>
) : (
<a href={synq.signInPath({ returnTo: '/dashboard' })}>Sign in</a>
)
}A layout that awaits synq.getSession() for <SynqProvider initialSession> does the same, in a component inside <Suspense> that renders the provider. To move an app over a page at a time, add export const instant = false beside a page's default export: it renders on each request, as it would without Cache Components, and builds as it is. Never call the three inside 'use cache' or 'use cache: private': pass me.sub to the cached function instead. Cache Components in the Next.js guide has the whole list.
Without Cache Components, your pages build and render as before, and nothing here is needed.
From 0.4 to 0.7
Sign-out ends the brand's session without asking (0.6.0)
On 0.4, Sign out sent the person to the brand's page, which asked "Sign out of Acme?", and someone who closed it stayed signed in at the brand. Now your server ends the person's session at the brand first. That page asks nothing, and the next Sign in asks how to sign in again, on a shared computer too.
-
@synqauth/nextjs:brandSignOutis'now'unless you set it. To keep 0.4's question, set it to'ask':export const synqConfig = defineSynqConfig({ brandSignOut: 'ask' }) -
@synqauth/js:signOut()on a client made withclientSecretdoes the same. PasssignOut({ endBrandSession: false })to keep the question. A public app has no secret, so its sign-out still goes to the brand's page, which asks. -
The brand's page still asks when the browser holds another sign-in there, or when your server can't reach Synq.
-
signOut()reads Synq's discovery document before it ends anything. If it can't reach Synq, the person stays signed in and can try again, instead of being half signed out. -
<UserButton>'s Sign out says "Signing out…" at once, and says so when the person is still signed in. In<AccountManager>, signing out "This device" under Devices signs out of the app and the brand.
Signing out has the whole flow.
"Manage account" links the brand's account page (0.6.0)
The session carries accountPage, the member profile Synq runs at the brand's /me, where people see the apps they allowed and delete their account. <UserButton>'s "Manage account" and <AccountPanel>'s "Account settings" link it when you pass no accountHref. On 0.4, "Manage account" didn't show without one. Pass accountHref to send people to your own page.
Adding a way in asks less (0.5.0)
A brand's linking settings changed their defaults:
link_reauth_windowis 2 hours (it was 10 minutes). Adding a wallet or another account within 2 hours of a sign-in on the device asks for no new sign-in.merge_empty_accountsis on. Adding a way in that an account with nothing else holds merges that account in, andwallets.add()answers itsmerged_from.move_proved_identitiesis on. A way in that another account holds, when that account keeps another way in, moves over on the proof the person just made.
To keep the old behavior, set them on the brand, in the dashboard's brand settings or with PATCH /v1/orgs/{org}/brands/{brand}. A link request also answers confirmation, what adding the way asks of the person first, so your page can say it. Adding and removing ways to sign in has each one.
Your users' API keys need their checksum (0.5.0)
If your API takes your users' API keys, a key now ends with a checksum, and isApiKey and createApiKeyVerifier refuse one without it before asking Synq. A key made before, with no checksum, no longer works: people make a new one.
Wallet sign-in on a phone (0.5.0)
@synqauth/solana-mobile's mobileWalletSignInUrl is gone. Sign in in place with useWalletSignIn() from @synqauth/solana-mobile/react-native, inside SynqMobileWalletProvider, or on the hosted page with useAuth().signIn({ method: 'wallet' }). mobileWalletSignIn runs inside your app's own transact, on its auth_token, and answers the wallet's authorization with the sign-in.
The management API's client
createManagementClient's types follow the management API. If your code calls these routes, change it:
- Token gates belong to a brand:
/v1/orgs/{org}/brands/{brand}/token-gates, and making one at the org's own route takesbrand(0.5.0). - Sending domains belong to a brand:
/v1/orgs/{org}/brands/{brand}/email-domains. The org's own/v1/orgs/{org}/email-domainsroutes are gone (0.5.0). - A way to sign in is on or off only on the brand's sign-in page,
PATCH /v1/orgs/{org}/brands/{brand}/sign-in-page. A brand'sbuilt_in_methods, a provider'senabled, and the providers'…/enableand…/disableroutes are gone (0.5.0). - A brand's theme has no
layout,method_orderorpanel_text. The sign-in page's placement orders the ways in (0.5.0). - The theme, sign-in page and member profile previews answer values (
look,view), never HTML (0.5.0). - An AI agent's changes apply at once by default.
require_approvaltakes the place ofmembers_may_turn_off, and the erroragent_approvals_requiredis gone. An approval request's id isapr_…, and its events areapproval_request.*(0.5.0). - Members and API keys can hold a role per brand. A brand a key holds no role in answers 404, as another org's does. A key made before keeps its permissions on all brands (0.5.0).
- A change the org's plan can't take answers 403
plan_feature_unavailableorplan_quota_exceededat once, withrequired_plan(0.5.0). - An org's email over a limit answers 429
rate_limited, naming the limit (0.5.0). - A
validation_failedproblem names a field the body doesn't take at its ownpointer, with the field it likely meant (0.6.0). POST /v1/orgs/{org}/billing/plantakes the free plan, which ends the paid one with its period. A plan change during a trial prorates nothing and keeps the trial (0.7.0).
Smaller changes
signInErrorMessagereads only its own codes, and each code has a page under Errors (0.5.0).- A
<SynqProvider>with no route mount behind it says so: the session's error isno_route_mount(0.7.0). invalid_grantandinvalid_clientsay which cause it was (0.7.0).npx synqauth initadds@synqauth/nextjsat its own version, and--codesets a project up with your own app (0.5.0).
From 0.7 to 0.8
These came in 0.8.0:
- A request body that isn't JSON answers 400
invalid_json, saying where it broke. A body sent withoutContent-Type: application/jsonanswers 415unsupported_media_type. Both were 500internal_error, andSynqErrorCodenamesinvalid_json. - A field left out says it's required and which values it takes, and a plan field lists the plans.
POST /v1/orgs/{org}/billing/planwith the plan the org is on keeps it: it renews a plan set to end, or calls off a waiting move down. The billing state hascalled_off_change, and the plan previewaction: keepandquotas.audit_retention_days.POST /v1/orgs/{org}/billing/trial/endends a trial now and pays for its plan, and…/trial/end/previewsays what it charges first. An AI agent asks for it withend_trial.- A brand move's preview says
roles_ending: how many members and pending invitations lose their role in the brand. - The audit action and webhook event
org.contacted. - Listing an org's webhooks answers
warnings:brands_limitedwhen the key or token sees webhooks in some brands alone, so the list leaves some out. Turning a webhook off ends the deliveries still waiting.
Nothing in this list changes how an app signs people in or out.
After 0.8.0
These come in the next version after 0.8.0:
@synqauth/nextjs:me(),getSession()andgetAccessToken()wait for Next'sconnection()after reading the cookies, since a session holds only until a time. With Cache Components, a page that read the session inside<Suspense>logged "Next.js encountered the unstable valueDate.now()while prerendering" on each request, and no longer does. They run for each request, never in a prefetch, so they can't run inside'use cache: private', which refusesconnection(). Without Cache Components nothing changes.npx synqauth init's/synqpage reads the request inside<Suspense>, so a new create-next-app project builds with it.
Moving a brand
Hand a brand to another organization with its users, apps and sign-in address unchanged. Who approves on each side, what moves, what changes, and what can block it.
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.