# Multi-Tenant Architecture

When building a multi-tenant SaaS application with Tigris, understanding how to structure your tenants is crucial for maintaining data isolation, tracking usage, and scaling efficiently. This guide explains how to map your customers to Tigris Organizations and architect your integration.

## Understanding the Hierarchy[​](#understanding-the-hierarchy "Direct link to Understanding the Hierarchy")

As a Tigris Partner, you receive a **Provider** account that acts as a container for all your customer organizations. Here's how the structure looks:

<!-- -->

| Component        | Description                                                                                                                                                         |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Provider**     | Your partner account. This identifies your platform and holds your signing key for API authentication. You manage all customer organizations through this provider. |
| **Organization** | An isolated container for a single tenant/customer. Each organization contains its own buckets, users, access keys, and has separate usage tracking and billing.    |
| **Bucket**       | S3-compatible storage container within an organization. Organizations can have multiple buckets.                                                                    |
| **User**         | A user ID from your system, passed as `user_id`. Each Partner API call says whether the user is an `Admin` or a `Member` with `user_role`.                          |
| **Access Key**   | S3-compatible credentials (access key ID + secret) scoped to an organization. Can optionally be restricted to specific buckets within that org.                     |

## Organizations Explained[​](#organizations-explained "Direct link to Organizations Explained")

### What is an Organization?[​](#what-is-an-organization "Direct link to What is an Organization?")

An **Organization** in Tigris is the fundamental unit of tenant isolation. Think of it as a security and billing boundary that completely separates one customer's resources from another's.

Each organization is:

* **Isolated** - Organizations cannot access each other's buckets, objects, or metadata
* **Self-contained** - Has its own users, access keys, buckets, and configuration
* **Independently tracked** - Usage and billing are calculated per organization
* **Separately managed** - Can be activated, deactivated, or quota-limited without affecting other organizations

## Recommended Tenancy Model[​](#recommended-tenancy-model "Direct link to Recommended Tenancy Model")

For most SaaS applications, we recommend **one Tigris organization per tenant**. This 1:1 mapping ensures the strongest isolation boundaries and simplest operational model.

### Provisioning Flow[​](#provisioning-flow "Direct link to Provisioning Flow")

When a user signs up in your system, you can create their organization and initial bucket via the API below, or through the [Partner Dashboard](https://www.tigrisdata.com/docs/partner-integrations/dashboard.md).

**1. Create their organization and initial bucket** in a single API call:

```
POST /v1/providers/{provider_id}/orgs/{org_id}/provision

Content-Type: application/json



{

  "bucket_name": "user-data",

  "org_name": "Acme Corp",

  "user_id": "user-123"

}
```

The `org_id` should be a unique identifier for that tenant in your system (e.g., `tenant-abc123` or `customer-{uuid}`).

**2. Store the returned credentials** - The response includes an access key that owns the new bucket:

```
{

  "bucket_name": "user-data",

  "access_key_id": "tid_...",

  "secret_access_key": "tsec_..."

}
```

This key has full control of the bucket, including deleting it. Keep it in your backend or delete it, and give your users a key with less access. See [The Provisioned Access Key](https://www.tigrisdata.com/docs/partner-integrations/access-control.md#the-provisioned-access-key).

**3. Create additional buckets** as needed using the Partner API or standard S3 CreateBucket API. All buckets remain isolated within the tenant's organization.

**4. Track usage and billing** - Query the organization-scoped billing and usage APIs to implement your own billing logic or cost allocation:

```
GET /v1/providers/{provider_id}/orgs/{org_id}/usage?starting_on=2024-01-01T00:00:00Z&ending_before=2024-02-01T00:00:00Z
```

## Managing the Tenant Lifecycle[​](#managing-the-tenant-lifecycle "Direct link to Managing the Tenant Lifecycle")

### Onboarding New Tenants[​](#onboarding-new-tenants "Direct link to Onboarding New Tenants")

Use the provision endpoint to create an organization and initial bucket atomically. This is idempotent, so retrying with the same parameters won't create duplicates:

```
POST /v1/providers/{provider_id}/orgs/{org_id}/provision

Content-Type: application/json



{

  "bucket_name": "main-storage",

  "org_name": "Customer Name",

  "user_id": "admin-user-id",

  "user_role": "Admin",

  "bucket_options": {

    "public": false,

    "storage_class": "STANDARD",

    "regions": "iad,fra"

  },

  "org_quota": {

    "limit_bytes": 107374182400

  }

}
```

The `user_role` field applies to this call only. See [Access Control](https://www.tigrisdata.com/docs/partner-integrations/access-control.md) for details on how roles and permissions work.

### Offboarding Tenants[​](#offboarding-tenants "Direct link to Offboarding Tenants")

To offboard a tenant, deactivate their organization. This immediately revokes access for all users and access keys. You can deactivate an organization from the [Partner Dashboard](https://www.tigrisdata.com/docs/partner-integrations/dashboard.md) or via the API:

```
PUT /v1/providers/{provider_id}/orgs/{org_id}

Content-Type: application/json



{

  "user_id": "admin-user",

  "active": false

}
```

**What happens when you deactivate:**

* All access keys are immediately invalidated
* No new resources can be provisioned
* Existing buckets and data remain intact for recovery or compliance
* Usage tracking continues for final billing calculations

**To permanently delete data:**

1. Deactivate the organization
2. Generate a final invoice for the period
3. Delete all buckets using the bucket deletion API
4. The organization remains for historical billing records

## Common Questions[​](#common-questions "Direct link to Common Questions")

### Which `user_id` Should I Use?[​](#which-user_id-should-i-use "Direct link to which-user_id-should-i-use")

Each access key and each provisioned bucket belongs to a `user_id`. Two models work:

* **One backend user per organization**, such as your service account. All keys and buckets belong to that user, so `Member` calls can manage all of them.
* **One user per person in your system.** Each person's keys stay separate, and List Access Keys with `Member` returns only that person's keys. To grant a role on a bucket that a different user provisioned, pass `user_role: "Admin"`.

### Is `org_id` Unique Across Tigris?[​](#is-org_id-unique-across-tigris "Direct link to is-org_id-unique-across-tigris")

No. An `org_id` is unique only within your provider. Use your own account or tenant ID.

### Are Bucket Names Unique per Organization?[​](#are-bucket-names-unique-per-organization "Direct link to Are Bucket Names Unique per Organization?")

No. Bucket names are global across all Tigris users, as in AWS S3. To prevent a name conflict, add a prefix such as your `org_id`, or generate the names.

### Which Units Do Usage and Invoices Use?[​](#which-units-do-usage-and-invoices-use "Direct link to Which Units Do Usage and Invoices Use?")

Invoices show storage in GiB-month and data transfer in GiB. One GiB is 1024³ bytes. Each metric from the usage API includes its own `unit`. The quota field `org_quota.limit_bytes` is a number of bytes.

## Next Steps[​](#next-steps "Direct link to Next Steps")

* **[Access Control](https://www.tigrisdata.com/docs/partner-integrations/access-control.md)** -- Learn how to use `user_role`, `buckets_roles`, and `access_key_scope`, with permission recipes for common setups
* **[Partner Integrations API Reference](https://www.tigrisdata.com/docs/partner-integrations/api/)** -- Complete API documentation for all partner endpoints

### Getting Help[​](#getting-help "Direct link to Getting Help")

Have questions about your integration? We're here to help:

* **Email:** <help@tigrisdata.com>
