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

# Multi-tenancy

> Learn how to use multi-tenancy to set up and customize engagement features and lifecycle messaging for each of your customers.

> [!NOTE]
>
> Multi-tenancy in Trophy is available on the Enterprise plan. Please [get in touch](mailto:support@trophy.so) to discuss your needs.

## What is multi-tenancy?

Multi-tenancy in Trophy allows you to power engagement features and lifecycle messaging on behalf of multiple of your own customers, and allow them to customize the features they use in their own applications and how they work.

Multi-tenancy is specifically designed for B2B SaaS platforms who want to offer a native engagement suite to their customers, but don't have the time or resources available internally to build and maintain multi-tenant engagement infrastructure themselves.

## How does multi-tenancy work?

Multi-tenancy works by creating 'tenant' records in Trophy for each of your customers, and configuring engagement features within the context of each tenant.

Customers who use multi-tenancy then make use of the [Admin API](/admin-api) to build internal control panels that allow their customers to manage their own engagement features within the constraints you set for them.

Similarly, customers who use multi-tenancy then make use of the [Application API](/api-reference) to power the UI that allows their customers' end-users to see and interact with the features they have exposed to them.

In this way, you can power complex engagement features for your own customers, and send lifecycle messages in each customer's brand, without building or maintaining any multi-tenant infrastructure yourself.

## What is a tenant?

A tenant is a logical grouping of users and data that represent the engagement features that a single customer uses within a multi-tenant Trophy account.

### Tenant ID

The `tenant.id` property is a unique identifier for each tenant that is used to scope API calls to a single customer.

You can use your existing internal ID for each tenant. You do not need to create a new ID for each tenant, as long as it is unique within your own system.

## Delivering multi-tenant engagement

There are two core components to delivering multi-tenant engagement: [customer control panels](#building-customer-control-panels) and [end-user UI](#powering-end-user-ui). Here we walk through how Trophy can help you deliver both with minimal effort.

### Building customer control panels

In order for customers to be able to manage their own engagement features, you need to provide them with a control panel within your own application that allows them to do so.

This means providing screens and functionality to choose which features to use, plus all the necessary toggles and switches to customize how each feature works.

Trophy's [Admin API](/admin-api) allows you to completely manage any feature available for configuration within the Trophy dashboard via headless API.

This allows you to serve control panels to your customers that allow them to manage their own engagement features within the constraints that you decide to set for them.

The only additional step required is to understand how to scope API calls from your control panel to the specific tenant that the customer belongs to. Read more about how to do this in the dedicated section on [setting tenant scope](#setting-tenant-scope).

### Powering end-user UI

The other critical part of delivering multi-tenant engagement is to power the UI that allows your customers' end-users to see and interact with the features your customers have exposed to them.

The [Application API](/api-reference) is already purpose built for powering in-app features within any application, and the process for powering features for your customers' end users is no different.

The only extra step required is to understand how to scope API calls to the specific tenant that the end-user belongs to. Read more about how to do this in the dedicated section on [setting tenant scope](#setting-tenant-scope).

## Setting tenant scope

Both the [Admin API](/admin-api) and the [Application API](/api-reference) work the same way for single and multi-tenant accounts. You use the same [client libraries](/api-reference/client-libraries.md) to power engagement features in both cases.

The only difference is that when using either the admin or application API within a multi-tenant account, you need to pass the `Tenant-ID` header to any API call that you want to scope to a specific tenant:

```bash Sending a multi-tenant API call {4} theme={null}
curl --request GET \
  --url https://api.trophy.so/v1/users/{id} \
  --header 'X-API-KEY: <api-key>' \
  --header 'Tenant-ID: <tenant-id>'
```

Trophy's client libraries support scoping API calls to a specific tenant by making use of the `tenantId` parameter in all methods:

```typescript Node {5} theme={null}
import { TrophyApiClient } from "@trophyso/node";

const trophyTenant = new TrophyApiClient({
  apiKey: 'YOUR_API_KEY',
  tenantId: 'customer_123',
});
```

```ruby Ruby {3} theme={null}
client = TrophyApiClient::Client.new(
  :api_key => 'YOUR_API_KEY',
  :tenant_id => 'customer_123',
)
```

```python Python {5} theme={null}
from trophy import Trophy

client = Trophy(
    api_key='YOUR_API_KEY',
    tenant_id='customer_123',
)
```

```php PHP {5} theme={null}
use Trophy\TrophyClient;

$trophyTenant = new TrophyClient([
    'apiKey' => 'YOUR_API_KEY',
    'tenantId' => 'customer_123',
]);
```

```java Java (Gradle) {3} theme={null}
TrophyApiClient client = TrophyApiClient.builder()
    .apiKey("YOUR_API_KEY")
    .tenantId("customer_123")
    .build();
```

```java Java (Maven) {3} theme={null}
TrophyApiClient client = TrophyApiClient.builder()
    .apiKey("YOUR_API_KEY")
    .tenantId("customer_123")
    .build();
```

```go Go {3} theme={null}
client, err := trophy.NewClient(
    option.WithAPIKey("YOUR_API_KEY"),
    option.WithTenantID("customer_123"),
)
```

```csharp .NET (C#) {3} theme={null}
var trophyTenant = new TrophyClient(
    "YOUR_API_KEY",
    tenantId: "customer_123"
);
```

## Frequently asked questions

> [accordion] How many tenants can I create?
>
> Each Trophy account can have an unlimited number of tenants.

> [accordion] How do I set the tenant scope for an API call?
>
> You can set the tenant scope for an API call by passing the `Tenant-ID` header to any API call.

## Get support

Want to get in touch with the Trophy team? Reach out to us via [email](mailto:support@trophy.so). We're here to help!


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