SynqDocs
Guides

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 sub stays 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 usesAfter the move, on a plan without it
Advanced theme settingsThe 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 domainIts email goes out as "Acme Kids via Synq".
A custom domainThe domain is suspended at the move, and removed after 14 days unless the plan has it then.
Its own sign-in provider appsThey keep working. Changing them needs a plan with them.
The organization's own botIt 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:

reasonWhat blocks itThe fix
transfer_pendingA request for the brand already waitsCancel it to ask again
org_unclaimedThe brand's organization is a development org nobody has claimed yetClaim it with its claim link, straight into your organization as a brand
brand_is_defaultThe brand is its organization's defaultName the brand that becomes the default (new_default_brand)
brand_is_lastThe brand is its organization's last, and an organization always has oneClose the organization with the move (close_from_org: true), or add another brand
own_bot_sharedThe organization's own bot serves another brand's communities tooConnect those through Synq's bot, or another of the organization's own
own_bot_conflictThe other organization has its own bot on that platform alreadyRemove its bot, or connect the brand's communities through Synq's bot
protected_name_unverifiedThe issuer slug uses a well-known service's nameAsk Synq support to verify the other organization for that name
brand_quotaThe other organization's plan has no room for another brandUpgrade its plan, or remove a brand
token_gate_quotaBoth organizations' gates together pass Synq's 100 for one organizationRemove 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 no issuer_slug, and its default_brand_id is null.
  • From Synq's MCP server, update_configuration's create_org takes the same first_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's brand_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:

  1. Read the preview with the other organization: GET /v1/orgs/{org}/brands/{brand}/transfer-preview?to_org=org_…, with new_default_brand or close_from_org when the preview asks for them. When you own that organization too, the answer has its side, to_org and preview_hash. For any other organization, to_org and preview_hash are null, and it's the brand's own side alone.
  2. Ask to move the brand with the same choices, confirm_data_responsibility: true, move_now: true and that preview_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_configuration with section brand_transfer_preview and the brand reads the preview. Section brand_transfers lists the organization's requests, and resource_id (btr_…) reads one.
  • Asking. request_configuration_change with operation request_brand_transfer, the brand, and the request's body as settings. decline_brand_transfer and cancel_brand_transfer take the request as resource_id.
  • Moving it now. When the person owns both organizations, request_brand_transfer takes move_now: true in settings. Asking reads the other organization's side for them and adds its preview_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_transfer takes the request as resource_id. Its settings are confirm_data_responsibility: true and the request's preview_hash, as brand_transfers read it. Asking checks the hash is still the request's (transfer_preview_changed if it isn't), so what the owner approves is exactly what the hash covers.
  • Telling the brand's users. Operation send_brand_transfer_notice takes an accepted request into the organization as resource_id, with empty settings. 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.

On this page