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.
A brand can move to another organization. It keeps everything that makes it work for the people who sign in: the same sign-in address, the same apps and client ids, the same users and their ways in, the same look. Only the organization that owns it changes. People move brands when one was started in the wrong organization, when a product is bought or spun out, or when a company brings its products into one organization.
A move takes both owners: the owner of the brand's organization asks, and the owner of the other organization accepts. The brand moves the moment they accept. A request nobody decides within 7 days expires, and nothing moves. When one person owns both, they move it now, in one step.
Who approves
- Asking. An owner of the brand's organization asks, and names the organization it goes to by its id. That organization's owner finds the id under Settings, Brand moves, and gives it to them.
- Accepting or declining. An owner of the other organization decides. Before they accept, they see exactly what moves and what changes on their side.
- Canceling. Either owner can cancel a request until it's decided.
- Expiry. A request lasts 7 days. Then it's
expired, and nothing moves.
Each step is the owner's alone, as a person. It needs org.brands.transfer, which only the owner holds (permissions): an admin can't ask, and an API key never asks or decides (403, with the fix). Asking, deciding and canceling each need a sign-in from the last 5 minutes, as other access changes do (fresh_sign_in_required). A brand has one request at a time.
Both owners confirm one line, word for word: "Globex becomes responsible for Acme Kids's users' data, and will tell them as its privacy terms require." The request carries it as data_responsibility_statement, so the dashboard and Synq's MCP server show the same words. Asking sends confirm_data_responsibility: true.
What moves with the brand
- Users. The brand's users, their ways in (passwords, passkeys, wallets and linked accounts), their sessions, consents and profiles. Their
substays the same, and they stay signed in. - Apps. The brand's apps keep their client ids, secrets and redirect URIs, so your integrations keep working with no change.
- Address and email. The issuer slug and its host, the brand's custom domains and every one of its sending domains, which are its own (the preview's
sending_domains). Slugs and hosts the brand retired stay its own. - Look and sign-in. The theme, logo, words and ways to sign in. A sign-in provider app goes with it only when it's the brand's own. One that is its organization's own stays behind: the brand then signs in through the new organization's own app for that provider, or Synq's, and the provider turns off where neither serves it. The request lists whose app each provider uses.
- Communities. The brand's Discord servers and Telegram groups, with the organization's own bot that serves them, and their announced windows.
- Token gates. The brand's token gates go with it, with their apps, roles and groups.
The brand's terms and privacy links stay as set, for the new organization to change after the move.
What changes at the organization level
What belongs to an organization, rather than to the brand, doesn't move. So after a move:
- API keys. The old organization's keys stop reaching the brand at once. The new organization's keys for All brands reach it from then on.
- Webhooks. The old organization's endpoints stop getting the brand's events. The new organization's endpoints for All brands start.
- Members and invitations. The new organization's members reach the brand through their roles on All brands. The old organization's members lose it, and their roles in that brand go (access). So do the roles in it that the old organization's pending invitations would give: such an invitation, once accepted, gives only the rest of what it says. Moving the brand back restores none of them, so invite people in the new organization for access there. The brand's own side of the preview counts both (
roles_ending). - Audit log. Both organizations record each step. The brand's earlier history stays in the old organization's audit log. The new organization's log starts at the move, with an entry that links back.
- Billing. The brand's monthly active users count toward the new organization from the move, and the old organization's count drops (plans and usage). The new organization needs room for one more brand on its plan.
- The default brand. The brand arrives as one of the new organization's brands, its default only if it has none, as in an organization made empty for it (below).
- Approval requests. Any open approval request for the brand is canceled, with the reason.
When the new organization's plan lacks something the brand uses, the request says what happens to each before its owner accepts:
| What the brand uses | After the move, on a plan without it |
|---|---|
| Advanced theme settings | The sign-in pages leave them out until the plan has them. The settings are kept. |
| No "Powered by Synq" | The sign-in pages say "Powered by Synq", and its bots' Verify button uses Synq's words. |
| Its own sending domain | Its email goes out as "Acme Kids via Synq". |
| A custom domain | The domain is suspended at the move, and removed after 14 days unless the plan has it then. |
| Its own sign-in provider apps | They keep working. Changing them needs a plan with them. |
| The organization's own bot | It keeps serving its servers and groups. Changing it needs a plan with it. |
Apps over the new plan's quota are allowed, as after a downgrade, and the request says so: the new organization can't make more until it's under.
The preview, and what blocks a move
Before asking, read the preview, or open the brand's Settings and, under Move or delete, the move's button. It says what moves: its users, apps, issuer, domains, communities and bots, whose app each sign-in provider uses, and what stays as set. It says what ends: how many of the organization's members, and of its pending invitations, hold a role in the brand itself (roles_ending), which ends at the move. It shows nothing of any other organization, and the target's side shows nothing of the brand's organization's people (roles_ending is null there). Reading it needs org.brands.view.
The other organization's owner sees the request with their own side added: what turns off on their plan (plan_changes), apps over its quota (apps_over_quota) and its room. Their side also has a preview_hash, the hash of exactly what they were shown, which accepting names. When the request's preview has changed since, accepting is refused and nothing moves, and the fix is to read the request again and accept what it shows then.
blockers lists what keeps the brand from moving now, each with its fix. Asking is refused while one of the brand's own side applies, with brand_transfer_blocked (409), its reason and the fix in detail:
reason | What blocks it | The fix |
|---|---|---|
transfer_pending | A request for the brand already waits | Cancel it to ask again |
org_unclaimed | The brand's organization is a development org nobody has claimed yet | Claim it with its claim link, straight into your organization as a brand |
brand_is_default | The brand is its organization's default | Name the brand that becomes the default (new_default_brand) |
brand_is_last | The brand is its organization's last, and an organization always has one | Close the organization with the move (close_from_org: true), or add another brand |
own_bot_shared | The organization's own bot serves another brand's communities too | Connect those through Synq's bot, or another of the organization's own |
own_bot_conflict | The other organization has its own bot on that platform already | Remove its bot, or connect the brand's communities through Synq's bot |
protected_name_unverified | The issuer slug uses a well-known service's name | Ask Synq support to verify the other organization for that name |
brand_quota | The other organization's plan has no room for another brand | Upgrade its plan, or remove a brand |
token_gate_quota | Both organizations' gates together pass Synq's 100 for one organization | Remove gates in either one |
The last four are the other organization's side: its owner sees them on the request, and they block accepting.
The last brand. When the brand is its organization's last, its owner chooses to close the organization with the move (close_from_org: true), since an organization always has a brand. Accepting then deletes the organization in the same step, as deleting it does: its API keys, webhooks and members go, and it's erased after 30 days. Nothing ever deletes an organization without that choice.
An organization that can't take a brand is refused with transfer_target_unavailable (422): there's no such organization, or it's Synq's own, unclaimed, disabled or deleted.
An organization to receive a brand
A brand often moves to an organization made for it, such as a new company's. Make that organization empty, with no brand of its own, so it doesn't start with a brand you'd delete after the move and so the brand fits a plan with room for one, such as Starter:
- In the dashboard, choose New organization from the organization menu, and under What does it start with? choose Nothing yet.
- Through the API, make the org with
first_brand: false. It takes noissuer_slug, and itsdefault_brand_idis null. - From Synq's MCP server,
update_configuration'screate_orgtakes the samefirst_brand: false.
Until a brand arrives, the organization's page says so, with the two ways to fill it: move one here, or make one. The first brand that arrives, moved in or made there, becomes its default.
Asking, accepting, declining and canceling
In the dashboard, open the brand's Settings and, under Move or delete, the move's button, which opens it in a dialog. Pick one of your other organizations, or enter the other one's id. When the preview asks, pick the new default brand, or agree to close the organization with its last brand. Then confirm the line and ask. A request that waits shows in that row instead, with a link to cancel it.
The organization's Settings, Brand moves, lists its id to give, each request to move a brand in, with its whole preview, Accept and Decline, the brands moving out, with Cancel, and the requests that ended.
Through the API, ask to move a brand with to_org, confirm_data_responsibility and, when the preview asks, new_default_brand or close_from_org. List the organization's moves, both ways (direction: outgoing or incoming), or read one. The other organization's owner accepts or declines, and either owner cancels. Deciding a request again answers the same; one that ended otherwise is brand_transfer_ended (409). Ended requests stay listed for 30 days, and the audit log keeps them for good.
Each step is recorded in both organizations' audit logs, and each is also that organization's webhook event: brand.transfer_requested, brand.transfer_accepted, brand.transfer_declined and brand.transfer_cancelled. A request that expires records nothing.
Accepting
In the dashboard, the other organization's owner opens Settings, Brand moves. An incoming request offers Accept while nothing blocks it. They confirm the line and press Accept and move Acme Kids here. While something blocks the move, the blockers show in its place.
Through the API, accept the request with confirm_data_responsibility: true and the preview_hash you read with it. The brand moves at once, in one step:
- When what moves or changes isn't what the preview showed any more, nothing moves:
transfer_preview_changed(409). Read the request again and accept what it shows then. - With no room on the plan for another brand, it's
plan_quota_exceeded(403). While something else blocks it, it'sbrand_transfer_blocked(409), with the fix. - Accepting again answers the same.
Both organizations record brand.transfer_accepted. The new organization's entry is the "moved from" one, naming from_org and transfer. Each is also the event of that organization's All brands endpoints.
Telling the brand's users. After the move, the new organization's owner can have Synq email the brand's users once, within 30 days: Email Acme Kids's users under Settings, Brand moves, or through the API. Each user with a verified address who may use their account and whom Synq may email hears who runs the brand now and is responsible for their data, that nothing changes for them, and where its privacy policy is, from the brand's own sender. It goes out in the background, and the request's notice says when the last went and how many it reached. It's recorded as brand.transfer_notice_sent.
Moving it now, when you own both
When the same person owns both organizations, they don't wait for themselves: the move happens in one step, under one fresh sign-in.
In the dashboard, pick the other organization you own. The dialog shows its side too: what its plan turns off, its room for the apps, and what blocks the move there. Confirm the line and press Move Acme Kids now. The brand moves at once, and the dialog takes you to it in its new organization.
Through the API:
- Read the preview with the other organization:
GET /v1/orgs/{org}/brands/{brand}/transfer-preview?to_org=org_…, withnew_default_brandorclose_from_orgwhen the preview asks for them. When you own that organization too, the answer has its side,to_organdpreview_hash. For any other organization,to_organdpreview_hasharenull, and it's the brand's own side alone. - Ask to move the brand with the same choices,
confirm_data_responsibility: true,move_now: trueand thatpreview_hash.
The answer is the request, accepted. Both organizations record brand.transfer_requested, then brand.transfer_accepted, as when two owners do it. What accepting refuses, moving it now refuses too: a preview that changed is transfer_preview_changed (409), and a plan with no room is plan_quota_exceeded (403). Any refusal leaves no request waiting. Synq checks that you own both organizations when you ask. Anyone else gets forbidden (403), with the fix: leave out move_now, and the other owner accepts as usual.
Staff moves
Synq's staff can see an organization's brand moves in Synq's staff admin, and cancel one with a reason. They can also move a brand on both owners' behalf, from the brand's move page, once the other organization is named and nothing blocks it. They confirm that both owners told Synq the new organization becomes responsible for the users' data, and give a reason. Both organizations' audit logs record what staff did, with the reason.
Through Synq's MCP server
An agent connected to Synq's MCP server reads a move and asks for each step. Asking for a move and accepting one always wait for the owner to approve them, since a brand moving is a change to people; declining, cancelling and the notice are made at once, unless the owner or the org asked to approve every AI agent change:
- Reading.
get_configurationwith sectionbrand_transfer_previewand the brand reads the preview. Sectionbrand_transferslists the organization's requests, andresource_id(btr_…) reads one. - Asking.
request_configuration_changewith operationrequest_brand_transfer, the brand, and the request's body assettings.decline_brand_transferandcancel_brand_transfertake the request asresource_id. - Moving it now. When the person owns both organizations,
request_brand_transfertakesmove_now: trueinsettings. Asking reads the other organization's side for them and adds itspreview_hash, so approving makes the request and accepts it at once, exactly as the words say, or moves nothing. For an organization they don't own, asking is refused (forbidden). - Accepting. Operation
accept_brand_transfertakes the request asresource_id. Itssettingsareconfirm_data_responsibility: trueand the request'spreview_hash, asbrand_transfersread it. Asking checks the hash is still the request's (transfer_preview_changedif it isn't), so what the owner approves is exactly what the hash covers. - Telling the brand's users. Operation
send_brand_transfer_noticetakes an accepted request into the organization asresource_id, with emptysettings. The approval page says who gets the email and that it goes once; asking again after that is refused.
Asking and accepting each answer in plain words what approving does, with the data-responsibility line, and an approve_url. The owner opens it in the dashboard, signed in within the last 5 minutes or within their approval window, and approving there is their confirmation of the line. Asking is refused at once with what approving would be refused with: a blocker, an organization that can't take a brand, or someone who isn't the owner (insufficient_permissions, org.brands.transfer). The agent never learns another organization's name from asking: the words name the other organization by its id unless the person is in it too. MCP tools lists every tool and its inputs.
One brand, many apps vs several brands
Should people use one account across your products? Yes means one brand with an app for each product; no means a brand for each.
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.