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

# Multi-tenancy

> Learn how to implement multi-tenant notifications in WorldVisa using contexts to isolate Inbox feeds, scope preferences, and personalize workflow content per tenant.

Multi-tenancy is a common requirement for applications that serve multiple organizations, workspaces, or customers from a single WorldVisa project. Tenants are also commonly called workspaces or organizations.

Typical multi-tenancy goals include:

* Grouping each subscriber's Inbox feed by tenant
* Scoping notification preferences per tenant
* Adjusting notification content and branding per tenant

WorldVisa supports multi-tenancy through [contexts](https://docs.worldvisagroup.com/developers/concepts/contexts.md). Use a `tenant` context to define tenant boundaries instead of duplicating subscribers, prefixing subscriber IDs, or maintaining separate workflows per tenant.

> [!NOTE]
>
> New to contexts? Start with [Contexts](https://docs.worldvisagroup.com/developers/concepts/contexts.md) to understand how context scoping, persistence, and Inbox filtering work.

## How multi-tenancy works in WorldVisa

Multi-tenancy in WorldVisa is built on top of contexts. A `tenant` context identifies which organization a notification belongs to.

When you trigger a workflow with a tenant context:

* Notifications are associated with that tenant
* The same subscriber can receive different notifications per tenant
* Inbox preferences are scoped to the subscriber and tenant context combination

When you initialize the Inbox with the same tenant context, the subscriber sees only notifications for that tenant.

## Implement multi-tenancy with contexts

**1. Define a tenant context**

A tenant context identifies a specific tenant. Use a simple string for the tenant ID, or a rich object when you need metadata such as company name, logo, or plan type.

```ts theme={null}
const tenantContext = {
  tenant: {
    id: "acme-corp",
    data: {
      name: "Acme Corporation",
      plan: "enterprise",
      logo: "https://cdn.acme.com/logo.png",
    },
  },
};
```

Contexts are auto-created on first use. Manage them from the **Contexts** section in the WorldVisa dashboard or through the Contexts API.

**2. Trigger workflows with a tenant context**

Pass the tenant context when triggering a workflow. Keep the subscriber ID stable - use your application's user ID, not a tenant-prefixed value.

```bash theme={null}
curl -L -g -X POST "${WV_API_URL}/v1/events/trigger" \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H "Authorization: ApiKey ${WV_API_KEY}" \
-d '{
"name": "invoice-paid",
"to": { "subscriberId": "user-123" },
"payload": { "amount": "$250" },
"context": {
    "tenant": {
        "id": "acme-corp",
        "data": {
            "name": "Acme Corporation",
            "plan": "enterprise"
        }
    }
}
}'
```

**3. Filter the Inbox by tenant**

Pass the same tenant context to the Inbox so each subscriber sees only notifications for their active tenant.

```tsx theme={null}
import { Inbox } from "@wv/react";

function TenantInbox({ userId, tenant }) {
  return (
    <Inbox
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriberId={userId}
      context={{
        tenant: {
          id: tenant.id,
          data: tenant.data,
        },
      }}
    />
  );
}
```

When a subscriber switches tenants, re-render the Inbox with the new context. WorldVisa refetches notifications and reconnects the WebSocket scope.

> [!NOTE]
>
> Secure tenant context in production with `contextHash`. See Inbox with context.

**4. Personalize content per tenant**

Use tenant metadata in templates with the `{{context}}` helper:

```liquid theme={null}
Hello {{subscriber.firstName}}, your {{context.tenant.data.plan}} plan
on {{context.tenant.data.name}} just renewed.
```

You can also branch workflow logic on tenant data in [step conditions](https://docs.worldvisagroup.com/developers/workflow/add-and-configure-steps/step-conditions.md). To use a different provider per tenant, see [a separate email provider for one tenant](https://docs.worldvisagroup.com/developers/integrations/integration-conditions.md#example-a-separate-email-provider-for-one-tenant).

## Tenant context in the Inbox

The Inbox uses exact-match context filtering. The tenant context on `<Inbox />` must match the context used at trigger time.

| Workflow context | Inbox context | Displayed? |
| - | - | - |
| `{ tenant: { id: "acme-corp" } }` | `{ tenant: { id: "acme-corp" } }` | Yes |
| `{ tenant: { id: "acme-corp" } }` | `{ tenant: { id: "globex" } }` | No |
| `{ tenant: { id: "acme-corp" } }` | `{}` | No |

Each subscriber gets a separate Inbox feed and preference configuration per tenant context.

## Frequently asked questions

> [accordion] Can subscribers manage different preferences per tenant?
>
> Yes. When you scope the Inbox with a tenant context, preferences are stored per subscriber and tenant context combination. A subscriber can enable email for one tenant and disable it for another.

> [accordion] Can I combine tenant context with other context types?
>
> Yes. You can pass up to five context keys per trigger - for example, `tenant` and `app` together. The Inbox must declare the same combined context to display those notifications. See [Contexts](https://docs.worldvisagroup.com/developers/concepts/contexts.md).

## Related guides

> [card] [Contexts](https://docs.worldvisagroup.com/developers/concepts/contexts.md)
>
> Learn what contexts are and how they work across WorldVisa.

> [card] [Manage contexts](https://docs.worldvisagroup.com/developers/workflow/advanced-features/contexts/manage-contexts.md)
>
> Create, update, and delete tenant contexts through the API.

> [card] [Integration conditions](https://docs.worldvisagroup.com/developers/integrations/integration-conditions.md)
>
> Route each tenant to a different email, SMS, chat, or push integration.


## Related topics

- [Multi-tenancy](https://docs.worldvisagroup.com/developers/inbox/advanced-features/multi-tenancy.md)
- [How do contexts work in WorldVisa?](https://docs.worldvisagroup.com/developers/concepts/contexts.md)
- [Integration conditions](https://docs.worldvisagroup.com/developers/integrations/integration-conditions.md)
- [Set up Inbox](https://docs.worldvisagroup.com/developers/inbox/setup-inbox.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.