---
title: Organizations
description: Create a team, invite members, and set roles.
sidebar:
  order: 1
---

Siglata keeps files and access permissions within an organization. Every project asset — including files, upload reservations, storage quotas, member lists, invitations, and Model Context Protocol (MCP) grants — is partitioned by organization ID. A user can belong to multiple organizations and switch between them. Each organization retains its own data and permissions.

## Multi-Tenant Architecture [#multi-tenant-architecture]

In Siglata, an **organization** is the foundational boundary for security and data retention:

```
┌────────────────────────────────────────────────────────────────────────┐
│                          Siglata Account                               │
│                         (alex@example.com)                             │
└──────────────────────────────────┬─────────────────────────────────────┘
                                   │
         ┌─────────────────────────┴─────────────────────────┐
         ▼                                                   ▼
┌─────────────────────────────────┐         ┌─────────────────────────────────┐
│     Acme Corp (org_1a2b3c)      │         │     Dev Studio (org_9z8y7x)     │
├─────────────────────────────────┤         ├─────────────────────────────────┤
│ • Role: Owner                   │         │ • Role: Member                  │
│ • Quota: 10 GiB Dedicated       │         │ • Quota: 10 GiB Dedicated       │
│ • Private Files & Trash View    │         │ • Private Files & Trash View    │
│ • Distinct Members & Invites    │         │ • Distinct Members & Invites    │
│ • Dedicated MCP OAuth Grants    │         │ • Dedicated MCP OAuth Grants    │
└─────────────────────────────────┘         └─────────────────────────────────┘
```

- **Strict Data Partitioning**: All database queries and object storage paths include the `organizationId`. Cross-tenant data leakage is prevented at both the database schema and application layers.
- **Independent Storage Quotas**: Each organization holds its own 10 GiB baseline quota (`limitBytes`), unaffected by file storage in other organizations.
- **Scoped Integrations**: Connected MCP clients and OAuth grants bind strictly to one organization at a time. Product MCP additionally requires that organization to hold a access tier before tokens issue or tools run.

## Role-Based Access Control (RBAC) [#rbac]

Siglata provides three distinct organizational roles with enforced hierarchy and least-privilege principles:

| Capability | `owner` | `admin` | `member` |
| :-- | :-: | :-: | :-: |
| **View, upload, download, and rename files** | ✓ | ✓ | ✓ |
| **Move files to trash and restore within 30 days** | ✓ | ✓ | ✓ |
| **Inspect organization storage metrics** | ✓ | ✓ | ✓ |
| **Connect personal MCP clients** | ✓ | ✓ | ✓ |
| **Invite new members and assign roles** | ✓ | ✓ | — |
| **Cancel pending invitations** | ✓ | ✓ | — |
| **Update member roles** | ✓ | ✓ | — |
| **Remove members from organization** | ✓ | ✓ | — |
| **Update organization name and URL slug** | ✓ | ✓ | — |
| **Promote members to Owner or delete organization** | ✓ | — | — |

Owners delete an organization with typed-name confirmation in the console, the CallScript operation `organization_delete` (empty input; grant-bound), or `POST /auth/organization/delete`. Deletion wipes the organization file plane first, then removes members, invitations, and the organization row.

### Role Safeguards & Invariants

- **Sole Owner Protection**: An organization must always have at least one active owner. A sole owner cannot be demoted or removed until another member is promoted to owner.
- **Admin Delegation**: Administrators can invite members, assign member/admin roles, and remove collaborators, but cannot demote or remove existing owners.
- **Real-Time Policy Evaluation**: Role checks (`requireRoleForScopes`) occur dynamically on every API request and MCP operation. Role changes take effect immediately without requiring users to log out.

## Member Invitation Lifecycle [#invitation-lifecycle]

Invite collaborators to your workspace securely using localized email invitations:

```
1. Admin sends invite ──> Localized invite email (en-US / pt-BR) ──> Token saved
        │
        ▼
2. Recipient opens link ──> Passwordless magic link sign-in ──> Accept invite
        │
        ▼
3. Member record created in DB ──> Workspace appears in switcher ──> Access active
```

### 1. Sending an Invitation

Administrators and owners can invite new team members with the `invitation_create` CallScript operation inside an MCP `execute` script or the `POST /auth/organization/invite-member` endpoint:

- Specify the recipient's **email address**.
- Select their assigned **role** (`owner`, `admin`, or `member`).
- Select the **language preference** (`en-US` or `pt-BR`) via the `x-siglata-locale` header to ensure transactional emails are sent in the recipient's native language.

### 2. Managing Pending Invitations

- Outstanding invitations are returned by the `invitations_list` CallScript operation or `GET /auth/organization/list-invitations`.
- Resend a pending invite with `invitation_resend` (same email and role as create).
- List invitations addressed to you across organizations with `invitations_mine`.
- Invitations remain valid for 7 days.
- An admin can cancel a pending invitation at any time before acceptance (`invitation_cancel`), which immediately invalidates the invite token.

### 3. Acceptance and Onboarding

- The recipient clicks the secure link in their email, or uses grant-bound `invitation_accept` / `invitation_reject` when the invite targets the OAuth grant's organization.
- Accept and reject refuse invitations for other organizations (`INVITATION_ORG_MISMATCH`); joining another org requires console accept and a new OAuth grant.
- Leave the grant-bound organization with `organization_leave`; the next MCP call fails membership.
- If they do not yet have a Siglata account, they authenticate immediately through a passwordless magic link — no password creation required.
- Upon confirming the invitation, their user account is linked as an active member, and the organization appears in their workspace switcher.

## Switching Workspaces [#switching-workspaces]

Users who belong to multiple organizations can switch contexts:

- **Siglata Console**: During sign-in and MCP authorization, the organization selection step sets the active workspace.
- **MCP AI Clients**: Each MCP connection grant is tied to a specific organization. Confirm the binding with the CallScript operation `principal_get` inside an `execute` script (`organizationId`, role, scopes); call `organization_get` when you need the name or slug. To connect an AI agent to multiple organizations, authorize separate server connections for each workspace.

## Member Removal & Immediate Revocation [#revocation]

When a member leaves a team or their access is revoked:

1. An administrator removes the user with the `member_remove` CallScript operation or the `POST /auth/organization/remove-member` endpoint.
2. The user's `member` record in the database is removed atomically.
3. Any active MCP tokens held by that user for the organization are immediately rejected on their next call with:
   ```json
   {
     "code": "ORGANIZATION_MEMBERSHIP_REQUIRED",
     "message": "Current organization membership is required"
   }
   ```
4. Authenticated binary file downloads and API requests are blocked immediately, ensuring zero unauthorized data retention.