SynqDocs
Guides

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.0

Add 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-https

Register 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:

app/page.tsx, before
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>:

app/page.tsx, after
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: brandSignOut is '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 with clientSecret does the same. Pass signOut({ 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.

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_window is 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_accounts is on. Adding a way in that an account with nothing else holds merges that account in, and wallets.add() answers its merged_from.
  • move_proved_identities is 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 takes brand (0.5.0).
  • Sending domains belong to a brand: /v1/orgs/{org}/brands/{brand}/email-domains. The org's own /v1/orgs/{org}/email-domains routes 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's built_in_methods, a provider's enabled, and the providers' …/enable and …/disable routes are gone (0.5.0).
  • A brand's theme has no layout, method_order or panel_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_approval takes the place of members_may_turn_off, and the error agent_approvals_required is gone. An approval request's id is apr_…, and its events are approval_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_unavailable or plan_quota_exceeded at once, with required_plan (0.5.0).
  • An org's email over a limit answers 429 rate_limited, naming the limit (0.5.0).
  • A validation_failed problem names a field the body doesn't take at its own pointer, with the field it likely meant (0.6.0).
  • POST /v1/orgs/{org}/billing/plan takes 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

  • signInErrorMessage reads 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 is no_route_mount (0.7.0).
  • invalid_grant and invalid_client say which cause it was (0.7.0).
  • npx synqauth init adds @synqauth/nextjs at its own version, and --code sets 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 without Content-Type: application/json answers 415 unsupported_media_type. Both were 500 internal_error, and SynqErrorCode names invalid_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/plan with 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 has called_off_change, and the plan preview action: keep and quotas.audit_retention_days.
  • POST /v1/orgs/{org}/billing/trial/end ends a trial now and pays for its plan, and …/trial/end/preview says what it charges first. An AI agent asks for it with end_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_limited when 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() and getAccessToken() wait for Next's connection() 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 value Date.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 refuses connection(). Without Cache Components nothing changes.
  • npx synqauth init's /synq page reads the request inside <Suspense>, so a new create-next-app project builds with it.

On this page