# Teams & members
URL: https://synquic.tech/docs/guides/teams-members.md

Invite other people into your Synq workspace, give them the right role, and understand the difference between your personal space and a shared team.

import { Step, Steps } from 'fumadocs-ui/components/steps';

Synq starts out as a space for one person: you. But most real work happens with other people: a teammate who
deploys the app, someone who only needs to look, a co-founder who owns the whole thing with you. This guide shows
how to bring people in and decide what each of them can do.

Think of your workspace like a shared office. You can hand someone a key (invite them), and each key opens
different doors (their **role**). Some keys open everything; some only open one room.

<Callout title="What you need first">
- A workspace you can see in the dashboard.
- The **email address** of the person you want to invite.
- You must be the **owner** or an **admin** of the workspace to invite people. (More on roles below.)
- Your panel must be reachable on a **public address**, such as `https://panel.example.com` (see
  [the panel's domain](/docs/guides/server-domains#the-panels-domain)). Until it is, the tab shows "Teammates need
  a public URL to reach this workspace" and invitations stay off.
</Callout>

## Invite someone

<Steps>

<Step>

### Open Users & team

In the dashboard, go to **Settings** and choose the **Users & team** tab. It lists everyone who has access
(**Active members**) and every invitation that hasn't been accepted yet (**Pending invitations**).

</Step>

<Step>

### Press "Invite member"

Click **Invite member** in the top-right. An inline **Invite a member** panel expands on the page.

<Callout title="Don't see the button?" type="info">
Only owners and admins can invite people. If you're a plain member, the button is hidden: ask an owner or admin
to send the invite for you.
</Callout>

</Step>

<Step>

### Enter their email and pick a role

Type the person's **Email**. Then choose a **Role** from the cards below the email box. Each role is explained in
the next section; **Member** is the usual choice for a teammate who will build and deploy. **Restricted** opens a
resource picker (**Initial resource access**) where you choose exactly what the invite unlocks.

</Step>

<Step>

### Send the invite

Under **Send via**, **Your mail system** shows **Ready** when your install can send email. Press **Send invite**:
Synq emails that address a link to join this workspace. The person shows up under **Pending invitations** ("Invited
as Member - expires ...") until they accept.

If no email system is set up, the panel says so and the action changes to **Create invite link**. Create it, then
press **Copy invitation link** beside the pending invitation and send the link yourself.

</Step>

</Steps>

<Callout title="Who sends the invite email?" type="info">
Your own install does, through the mail system you set up (**Settings**, **Email**, or your own mail server). The
hosted-cloud relay is switched off in Synq. If you haven't set up email, use **Create invite link** and send the link
yourself.
</Callout>

<Callout title="New accounts: instance administrator only" type="info">
Accounts on a self-hosted install are created by invitation only; there is no public sign-up. Workspace owners and
admins can invite people who **already have an account** on this install. Inviting an email address that has no
account yet creates a new account, and only an **instance administrator** (the admin account created when Synq was
installed) can do that.
</Callout>

## What each role can do

A role is a bundle of permissions. Synq has four, from most powerful to least:

- **Owner**: the person who created the workspace. Can do everything, including changing other people's roles and
  removing members. You can't invite someone straight in as owner, but an owner can promote an existing member to
  owner later, from the role dropdown on the **Users & team** tab.
- **Admin**: everything a member can do, **plus** managing members (sending and cancelling invites, removing people)
  and reading the [audit log](/docs/guides/audit-log).
- **Member**: full read and write access to everything in the workspace: create projects, deploy, edit environment
  variables, and so on. A member **cannot** manage other people.
- **Restricted**: starts with **no** access. When you invite a restricted member you pick exactly which resources
  (specific projects, servers, and so on) they're allowed to reach. Use this for someone who should only touch one
  or two things.

<Callout title="Team roles are broad by design, so invite people you trust (beta)" type="warn">
Owner, Admin and Member are **coarse, high-trust roles**. A **Member** can deploy, create and **delete** projects and
servers, run jobs, manage domains, and read and write environment variables: nearly everything an Admin can, minus
managing people and reading the audit log. So add someone as **Member or Admin only if you'd trust them with
near-admin control** of the workspace.

For a collaborator who should be limited to specific things, use the **Restricted** role with per-resource grants,
or hand out a **scoped or read-only [access token](/docs/security/permissions#access-tokens-follow-the-same-rules)**.
Those are the paths that actually enforce *read vs write vs admin* and confine access to specific projects or
servers. Fine-grained, per-action limits for the standard roles are still on the roadmap (**beta**), so treat a team
workspace as a **trusted-collaborator** workspace for now.

This is about permissions *inside* one workspace. **Between** workspaces, isolation is enforced: one organization can
never see or touch another's projects, servers or secrets (see [Isolation](/docs/security/isolation)).
</Callout>

<Callout title="Changing a role later" type="info">
Only the **owner** can change someone's role. On **Users & team**, each member (except you) has a role dropdown next
to their name: pick a new role and it applies right away. Owners and admins can also **Remove member** with the
trash icon; Synq asks you to confirm first. You can't change or remove yourself.
</Callout>

<Callout title="Granting server access is high-blast-radius" type="warn">
Giving a member access to a **server** (when inviting, or by editing their access on **Users & team**) is a bigger
deal than a role change: on that server they can reach every deployment and its **data**, the apps running on it,
injected **secrets and environment variables**, a live **terminal**, and any **GitHub tokens** used for its deploys.
That's why Synq asks "Grant full server access?" and spells out exactly what the new access exposes before it takes
effect. Grant server access only to people you trust with everything on that box.
</Callout>

For the full rules on how permissions and per-resource access are enforced, see
[Permissions & roles](/docs/security/permissions).

## Accept an invite

This is what the *invited* person does after you send it.

<Steps>

<Step>

### Open the link in the email

The invite email contains a link. Clicking it opens a page that says **You're invited** (or **Join [workspace
name]** once you're signed in).

</Step>

<Step>

### Sign in or create an account

If you're not signed in yet, the page offers **Sign in** and **Create account**. Use the **same email address the
invite was sent to**: Synq checks that they match.

</Step>

<Step>

### Press Accept

Once signed in with the right email, the page shows the workspace name and the role you're joining as, with
**Decline** and **Accept** buttons. Press **Accept**. You'll see **You're in**, and Synq sends you to the dashboard
for that workspace.

</Step>

</Steps>

Once in, each person should turn on [two-factor authentication](/docs/guides/two-factor) for their own account under
**Settings**, **Security & 2FA**.

## Personal vs team workspaces

Every Synq workspace is called an **organization**. When you first sign up, Synq creates a **personal workspace**
just for you: your own projects, servers and domains, with no one else in it.

You have two ways to work with other people:

- **Invite them into your personal workspace.** Fine for a small group: everyone shares the same projects and
  servers. Use the **Invite member** button described above.
- **Create a separate team organization.** A clean, shared space that stays isolated from your personal projects.
  On **Users & team** (while viewing your personal workspace), open the **⋮** menu next to the heading and choose
  **Create a team organization**. Enter a **Team name** and press **Create team**: Synq switches you into the new
  shared workspace. Its projects and members are completely separate from your personal ones.

You can belong to more than one organization and switch between them. A team organization has its own members and
roles, exactly as described above.

In a team workspace, the owner's **⋮** menu on **Users & team** has **Manage workspace**: rename it, stop all its
projects (**Stop all projects**), or **Delete workspace** (this tears down its projects and can't be undone). Other
members see **Leave workspace** instead. A personal workspace can't be deleted or left.

<Callout title="Which should I pick?" type="info">
If it's just you and one or two trusted people, inviting into your personal workspace is simplest. If you want a
shared space that isn't tangled up with your own experiments, or you expect the group to grow, create a team
organization.
</Callout>

## Troubleshooting

<Callout title="“This invite is for … You're logged in as …”" type="warn">
The invite was sent to one email but you're signed in with a different one. Sign out, then sign back in (or create an
account) using the exact address the invitation was sent to. If you've lost the link, ask an owner or admin to copy
it from **Pending invitations** or send a fresh one.
</Callout>

<Callout title="The invite email never arrived" type="warn">
Check the spam folder first. If no mail system is set up, nothing can deliver it: use **Create invite link**, then
**Copy invitation link** from the pending invitation and send it directly. Setting up
[email](/docs/guides/email-webmail) fixes it for future invites.
</Callout>

<Callout title="“Failed to send invite”" type="error">
Usually this means you don't have permission (only owners and admins can invite), the person is already a member,
or the address has no account yet and you aren't an instance administrator. Confirm your own role on **Users &
team**, and check the **Active members** and **Pending invitations** lists to see if they're already there.
</Callout>

## Related guides

<Cards>
  <Card title="Permissions & roles" href="/docs/security/permissions" description="The full picture of how Synq decides who can do what, including per-resource grants." />
  <Card title="Two-factor authentication" href="/docs/guides/two-factor" description="Protect every account with a code from an authenticator app." />
  <Card title="Audit log" href="/docs/guides/audit-log" description="See who did what in the workspace." />
</Cards>