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

# Multi-tenancy & Roles

> How organisations are isolated, how the three-tier role model works, and the one invariant that even superadmins can't cross.

Seyn handles clients' operational data: chat logs, deal documents, emails. Tenant isolation is therefore not a feature; it's an invariant the rest of the platform is built on.

## The isolation model

* **Organisations are the tenancy boundary.** Each Seyn client is one organisation. Users belong to organisations through memberships.
* **Every piece of client data carries its organisation.** Raw records, events, rules, libraries, chat threads, inference logs: all of it, with no exceptions.
* **Every query filters by organisation.** The scope is derived from the authenticated context, never from URL parameters, headers, or request bodies a caller could manipulate.
* **The org context comes from signed claims** for dashboard users, or from the API key's binding for API and MCP access. A given API key sees exactly one organisation, even if its creator belongs to several.

Cross-org leak detection runs as part of the platform's verification checks, on top of the structural guarantees.

## The three role tiers

Roles form a hierarchy: `org:member < org:admin < platform:admin`.

| Role             | Who                                        | What they can do                                                                                                    |
| ---------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
| `org:member`     | Client team members (default for invitees) | Chat, visualisation, settings, document upload.                                                                     |
| `org:admin`      | Client team leads                          | Everything members can, plus org management: invite members, manage the org's API keys, create document connectors. |
| `platform:admin` | Seyn staff                                 | Operational surfaces: connector setup, extraction runs, inference logs, query explorer.                             |

Role checks happen in two places, deliberately mirrored: the backend enforces them on every endpoint, and the dashboard gates navigation by the same hierarchy. The frontend gating is UX; the backend check is the security boundary.

## The superadmin invariant

`platform:admin` is a **navigation power, not a query bypass**. Seyn staff can switch into a client organisation to operate it, but once switched in, every query still scopes to that organisation. There is **no cross-tenant query path**: no "all orgs" data endpoint, no admin override on the scope filter.

<Note>
  This is the difference between "our staff can see your data when operating your tenant" (true, and necessary to run the service) and "there exists code that queries across tenants" (false, by construction). The first is a policy; the second is an attack surface we chose not to build.
</Note>

## Tenancy at every boundary

| Surface         | How tenancy binds                                                                                                       |
| --------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Dashboard       | Signed session → active organisation → query scope.                                                                     |
| Public API      | `sk_live_*` key → one organisation, set at key creation. See [Authentication](/authentication).                         |
| MCP server      | API key resolves to an organisation; every tool result is scoped to it.                                                 |
| Background jobs | Org context travels with the job; per-org concurrency caps prevent one tenant's extraction run from starving another's. |

## Common mistakes

| Symptom                                                        | Cause                                                                       | Fix                                                                   |
| -------------------------------------------------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| API returns `NOT_FOUND` for an ID you can see in the dashboard | The API key belongs to a different organisation than the one you're viewing | Check which org the key was created in; create a key in the right org |
| A member can't see connectors or extraction runs               | Operational surfaces are operator-scoped by design                          | Members consume knowledge; operators run the machine                  |
| Expecting one API key to span multiple client orgs             | Keys are single-org on purpose; that's the isolation guarantee              | Create one key per organisation                                       |

## Related

<CardGroup cols={2}>
  <Card title="Security & Trust" icon="shield" href="/platform/security">
    Credentials, rate limits, and data-handling guarantees.
  </Card>

  <Card title="Authentication" icon="key" href="/authentication">
    API keys: creation, rotation, error codes.
  </Card>
</CardGroup>