SynqDocs
Concepts

Access

Who in your org can do what, across the org and in each brand, and what an API key, a webhook endpoint and an AI agent can reach.

Everyone and everything that manages your org holds two kinds of role: one across the org, and one in each brand it works on. A brand it holds no role in is one it can't see: its routes answer 404, as another org's brand does, and it drops out of the org's lists.

Roles across the org

Each member has one org role:

RoleWhat it may do
OwnerEverything, including deleting the org and handing it over. The owner is Brand admin in every brand, always, so an org is never left without one.
AdminEverything but deleting the org and handing it over: members, billing, settings, adding and deleting brands.
BillingThe plan, its invoices and the org's own audit entries. No brand.
MemberReads the org itself and its plan, to ask the owners for another. What they do in a brand is their brand roles'.

An org's own roles, made from any set of permissions, can be given as an org role too.

Opening the org needs no permission: every member sees the orgs they're in and what they may do in each. So a role of the org's own holds only what it's for, and the permissions reference says what each one allows. org.read, which every built-in org role holds, reads the org's own record; a member whose org role leaves it out still opens the org and works in its brands, but can't read that record, leave the org themselves, ask the owners for another plan, or use approval requests for their AI agents' changes.

Roles in a brand

Each member, invite and API key holds a role in each brand it works on, or one on All brands. All brands includes every brand added later.

RoleWhat it may do in the brand
Brand adminEverything in the brand: its settings, sign-in page and domains, apps, APIs, sign-in methods, users, token gates and communities, its webhooks and API keys, and reading who can reach it.
DeveloperIts apps, APIs and sign-in methods' apps, and its webhooks and API keys, and reads the rest.
SupportFinds its users and helps them (disabling them, ending their sessions, resetting their ways in), and reads the rest. No settings.
ViewerReads everything in the brand but its API keys.

An org's own role can be a brand role too: it gives what its permissions mean in that brand.

A holder can have a role on All brands and another in one brand; in that brand it gets both. Left out when someone is invited or their org role changes, their brand roles follow their org role: Brand admin on All brands for an admin, Viewer on All brands for a member, none for billing.

Nobody gives more than they hold: a role across the org or in a brand is at most what the person giving it can do there. Roles in one brand at a time need Scale or above (plan_feature_unavailable otherwise); a role on All brands works on every plan.

Roles in a brand end if the brand moves to another org, and so do the ones a pending invitation would give in it. Moving it back doesn't restore them: invite people in the new org for access there. The dashboard says so where it gives brand roles: inviting someone, and a member's roles on Members.

Change a member's roles with role, brand_roles or both, and invite with them. The invitation's email and the page its link opens say what the person will be able to do: their role across the org and each brand role, each brand by its name, with what each role lets them do, and that they won't see the org's other brands (what an invite offers). Who can reach a brand lists its people with their roles there; the dashboard shows it on each brand's Access page.

The org's own actions

Some actions are the org's, never a brand's: its members and roles, billing, its settings, adding a brand, deleting one and moving one to another org. They want the permission across the org. A credential that holds it only in some brands is refused with 403 insufficient_permissions, in words that say so: "This credential has org.members.view only in some of this org's brands, and this is for the whole org."

The org's lists that span brands (brands, token gates, Discord servers, Telegram groups, community activity, change requests, the audit log, API keys and webhooks) show only the brands the caller holds the permission in.

API keys

An org API key holds its permissions across the org, and a role or a permission set in each brand it works in (brand_roles):

  • A key for some brands acts in them alone. Across the org it only reads the org (org.read). In another brand it gets 404.
  • A key for All brands (brand_roles left out, or "brand": null) reaches every brand there is and will be. Only the org's owner, or a key for All brands, makes one: anyone else gets all_brands_owner_only.

A key never holds more than its maker in any brand. The dashboard makes a new key for the brand in view, as a Developer, unless you choose otherwise.

A permission that changes something comes with the one that reads it, in a key or a role of the org's own as in every built-in role: given org.brands.edit, a key holds org.brands.view too, and given org.edit, org.read. The key's permissions say so.

curl -X POST "$SYNQ_API/v1/orgs/$ORG/api-keys" \
  -H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d '{
    "name": "Acme deploys",
    "permissions": ["org.read"],
    "brand_roles": [{ "brand": "brd_01h455vb4pex5vsknk084sn02q", "role": "developer" }]
  }'

Webhook endpoints

A webhook endpoint gets the events of the brands it names (brands), or of All brands (brands: null). Only an All brands endpoint gets the org's own events, the ones that happen in no brand: members, billing, brand moves. An endpoint for some brands needs org.webhooks.edit in each of them; an All brands endpoint needs it across the org.

The audit log

Every audit entry says the brand it happened in, if any. A brand role with org.auditLog.view reads that brand's entries; the org's own entries (no brand) want it across the org, which the owner, admins and billing have. A key's or an endpoint's own entries are its brand's when it works in exactly one.

The dashboard's Audit log says when some entries are hidden from a role, and which roles see them. It names each teammate the role can see: everyone, for a role that reads the members across the org; otherwise those who hold a role in its brands, as each brand's Access page lists them. Anyone else shows as "A teammate".

AI agents

An MCP connection acts as its person, with exactly their roles. get_connection lists their role across each org and in each brand; a brand they hold no role in reads as not there. Approving a change request needs the right role in that change's brand.

When someone leaves

Leaving an org, or being removed from it, ends the person's access to it at once. Every request checks membership afresh, so their dashboard sessions, the CLI and the AI agents they connected can't act in the org from their next request on. The change requests their agents asked for go with them, and so do the setup codes they made (a setup code gets an app a new secret) and their unused requests to connect a Discord server or Telegram group. Their sessions in other orgs are theirs and stay.

That holds if they come back, too. Invited back, they join with their sessions in the org ended at the moment they left, so no sign-in of theirs from before then works there again: they sign in afresh, and any app or agent they connected before needs connecting again. Until then a sign-in from before answers 403 fresh_sign_in_required with reason sessions_ended.

API keys belong to the org, not to whoever made them, so they keep working: a key's created_by names its maker. Revoke any key a departed teammate holds the secret of, after switching what uses it to a new one.

Who left stays on the record. The dashboard's Members lists them under Former members: the role they had, when they joined and left, and whether they left on their own or who removed them, each opening what they did in the audit log, whose Who filter offers them too, marked with the day they left. The API's list is the same:

curl "$SYNQ_API/v1/orgs/$ORG/former-members" \
  -H "Authorization: Bearer $TOKEN"

It comes from the audit log's member.left and member.removed entries, so it goes as far back as the org's plan keeps its log, and needs org.members.view, as the members list does. Pass a former member's user_id as the audit log's actor to see what they did.

To make a teammate sign in again without removing them (a lost laptop, a sign-in that may not be theirs), end their sessions: their row in the dashboard's Members, End sessions, or the API:

curl -X POST "$SYNQ_API/v1/orgs/$ORG/members/$USER/end-sessions" \
  -H "Authorization: Bearer $TOKEN"

From then on, any sign-in of theirs from before acts in this org no more, and answers 403 fresh_sign_in_required with reason sessions_ended, until they sign in again; an app or agent they connected before needs connecting again. They stay a member, their other orgs aren't touched, and their setup codes stop working. It needs org.members.edit, never reaches someone who can do more than the caller, and only the owner ends the owner's. It's recorded as member.sessions_ended.

Before brand roles

Everyone who had access before brand roles kept exactly that access, on All brands: owners and admins are Brand admin, a member with one of the org's own roles holds it on All brands, and a plain member is Viewer on All brands, with an org role, "Member (from before brand roles)", that keeps what a member read across the org. Every API key holds its permissions on All brands, and every webhook endpoint gets All brands' events.

On this page