> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.oryxa.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Organizations and Team Members in Synq

> Understand how Organizations structure your team inside a Tenant, and how to manage members and roles via the dashboard or API.

Within every Tenant, Synq uses **Organizations** to group the people who work on your commerce operations. An Organization is the unit you manage day-to-day: it holds your team members, their roles, and the permissions that govern what each person can do. If your Tenant is the outer boundary of your workspace, your Organization is the team operating inside it.

## Roles

Every team member in an Organization is assigned one of two roles:

<CardGroup cols={2}>
  <Card title="Admin" icon="shield-check">
    Full access to all settings, integrations, and team management. Admins can invite new members, change roles, and remove users from the Organization.
  </Card>

  <Card title="Member" icon="user">
    Operational access to commerce features — managing products, orders, and inventory — without the ability to change team membership or billing settings.
  </Card>
</CardGroup>

<Note>
  Only **Admins** can invite new members or change the role of an existing member. If you need to add someone to your Organization and you do not see the invite option, ask an Admin on your team to send the invitation.
</Note>

## Managing team members

You can manage team members through the **Settings → Team** page in the Synq dashboard, or programmatically through the API. Both approaches apply the same role-based access rules.

### Invite a new member

Send a `POST` request to `/api/v1/organization/members` with the new member's email address and their intended role. Only users with the **Admin** role can call this endpoint.

```bash theme={null}
curl -X POST https://api.synq.io/api/v1/organization/members \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jamie@example.com",
    "role": "member"
  }'
```

```typescript theme={null}
const response = await fetch("https://api.synq.io/api/v1/organization/members", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    email: "jamie@example.com",
    role: "member",
  }),
});
```

**Request body**

| Field   | Type   | Required | Description                                |
| ------- | ------ | -------- | ------------------------------------------ |
| `email` | string | ✅        | Email address of the person to invite      |
| `role`  | string | ✅        | `"admin"` or `"member"` (case-insensitive) |

A successful invitation returns `201 Created` and sends an email to the invitee.

<Warning>
  This endpoint requires an Admin token. Requests made with a Member token will be rejected with `403 Forbidden`.
</Warning>

### List all members

Retrieve every member in your Organization with a `GET` request.

```bash theme={null}
curl https://api.synq.io/api/v1/organization/members \
  -H "Authorization: Bearer <your-token>"
```

**Example response**

```json theme={null}
{
  "members": [
    {
      "id": "c9a1e847-2f3d-4c10-b8e5-0a7d6f219abc",
      "email": "alex@example.com",
      "role": "admin",
      "status": "active",
      "joined_at": "2024-11-03T09:14:22Z"
    },
    {
      "id": "d72b3f10-8a4e-4901-b3c7-5e1f9a038def",
      "email": "jamie@example.com",
      "role": "member",
      "status": "invited",
      "joined_at": null
    }
  ],
  "total": 2
}
```

The `status` field indicates whether the user has accepted their invitation (`active`) or is still pending (`invited`).

## Dashboard workflow

<Steps>
  <Step title="Open Team Settings">
    In the Synq dashboard, click your organization name in the top navigation bar and select **Settings → Team**.
  </Step>

  <Step title="Click Invite Member">
    Select **Invite Member**, enter the person's email address, choose their role, and confirm.
  </Step>

  <Step title="Member accepts the invitation">
    The invitee receives an email with a secure sign-up link. Once they complete registration, their status changes from **Invited** to **Active**.
  </Step>

  <Step title="Adjust roles at any time">
    Open the **⋯** menu next to any member's name to change their role or remove them from the Organization.
  </Step>
</Steps>

<Warning>
  Removing a member is immediate and irreversible through the API. The removed user loses access to the Organization as soon as the request succeeds. If you removed someone by mistake, re-invite them using the same flow.
</Warning>

## Frequently asked questions

<Accordion title="Can an Organization have more than one Admin?">
  Yes. We recommend keeping at least two Admins in every Organization to avoid losing administrative access if one person leaves.
</Accordion>

<Accordion title="Does the invitee need an existing Synq account?">
  No. If the email address is not associated with an existing account, Synq creates one when the invitee accepts the invitation.
</Accordion>

<Accordion title="Can I belong to more than one Organization?">
  Yes. A single user account can be a member of multiple Organizations, even across different Tenants. Switch between Organizations using the organization selector in the top navigation bar.
</Accordion>