> 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/embed/embedding/understanding-tenancy.md).

# Customers and tenancy

How the embed token scopes the widget to one customer, and to one person at that customer

Every widget session in fastn is scoped twice: to one **customer** (a company using your product), and to one **person** at that customer. Both come from the embed token your backend mints. Nothing in the iframe URL changes either of them.

### The customer

The customer is named when your backend mints the token, by the `x-org-id` header (or `orgId` in the body). Either value can be your own id for the customer (the external reference you registered it under) or fastn's id for it (see [Finding Your Org Identifier](https://docs.fastn.ai/embed/api-keys/finding-your-org-identifier.md)). A token always belongs to exactly one customer, and the widget shows that customer's integrations and connections only.

A token minted without a customer is refused (`400`, code `EMBED_TOKEN_REQUIRES_END_ORG_ID`) unless you explicitly ask for an organization-level token with `allowOrgLevel: true`. That kind of token is for previewing your own organization only; never hand one to a customer.

### The person

Within a customer, per-user isolation keys on the **user id**:

* send `userId` in the token request body, or
* send `x-user-id` on the token request, attested with an identity hash when the API key has identity verification turned on (see [API keys](https://docs.fastn.ai/embed/api-keys.md)).

`userEmail` and `userName` are for display only; they do not decide whose session it is. If you send no user id at all, each token gets a random `embed_usr…` id, so nothing a person does carries over to their next session. Send a stable id from your own user table.

### How it's set in the embed

The iframe takes the token, and only the token:

```
https://api.fastn.dev/api/v1/embed/iframe?token=<token>
```

The customer and the user are inside the token, put there when your backend minted it. You do not add a `tenant-id` parameter. If an older snippet still carries one, it must name the same customer as the token: when the two disagree, the widget refuses the session rather than guess. Drop the parameter and let the token name the customer.

### What this means for your backend

1. When a signed-in person opens the page that hosts the widget, look up which customer they belong to and their user id.
2. Mint a token for that customer and that user.
3. Hand only the token to the browser.

See [Generating Embed Tokens](https://docs.fastn.ai/embed/embedding/generating-embed-tokens.md) for the full request.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.fastn.ai/embed/embedding/understanding-tenancy.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
