> For the complete documentation index, see [llms.txt](https://docs.fastn.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fastn.ai/tutorials/developer/understanding-tenancy.md).

# Understanding Tenancy

Fastn supports two ways to scope connections within the same embed: org-level (shared) and user-level (per individual). Choosing correctly determines who can see and use which connections.

### The distinction

**Org-level (shared)** — One connection serves the entire customer organization. Anyone in that organization uses the same connection. Use this for shared systems of record.

**User-level (per individual)** — Each user has their own connection, isolated from other users in the same organization. Use this for resources tied to one person's identity.

{% hint style="info" %}
This is **not** an "internal vs external user" distinction, and it is **not** about who can edit. It is strictly shared-vs-personal, based on who owns the connected resource.
{% endhint %}

### How to decide

Ask who owns the resource being connected:

| Resource type                         | Scope      | Examples                                                           |
| ------------------------------------- | ---------- | ------------------------------------------------------------------ |
| Shared systems of record              | Org-level  | CRM, project management, data warehouse, shared messaging channels |
| Personal identity, inbox, or calendar | User-level | A person's email, personal calendar, individual account            |

A shared Salesforce instance that the whole company uses is org-level. An individual sales rep's email inbox is user-level. Most customers need both in the same embed — a shared CRM connection plus each rep's own email.

### How it's set in the embed

The tenancy choice is encoded in the iframe URL and the identity the token is minted with.

**User-level (per individual):**

```
https://live.gcp.fastn.ai/api/v1/embed/iframe?tenant-id=<endOrgId>&token=<token>
```

The `tenant-id` parameter is present. Combined with the `userEmail` and `userName` in the token body, connections are isolated to that individual user.

**Org-level (shared):**

```
https://live.gcp.fastn.ai/api/v1/embed/iframe?token=<token>
```

No `tenant-id` parameter. Connections are shared across the organization.

### Persona examples

These illustrate the typical mix of shared and personal connections per buyer persona:

| Persona                            | Org-level (shared) | User-level (personal)         |
| ---------------------------------- | ------------------ | ----------------------------- |
| Integration Backlog Owner (VP Eng) | Jira, Slack        | Google Calendar               |
| Product Manager                    | Ad account, CRM    | Slack alerts                  |
| CRO                                | Salesforce         | Each rep's email              |
| Head of Solution Engineering       | Snowflake, CRM     | Each tester's sandbox account |
| Head of Customer Success           | Usage-data system  | Each CSM's calendar / email   |

The through-line: shared systems of record map to org-level; personal identity, inbox, or calendar maps to user-level. Most customers need both, which is why both flavors exist.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.fastn.ai/tutorials/developer/understanding-tenancy.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.