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

# Multi-Tenant

> Manage multiple chatbots from a parent account

Multi-tenant architecture lets you manage multiple independent chatbots from a parent account.

<Note>
  Multi-tenant is available on the **Enterprise** plan.
</Note>

## Concept

```
Parent Account (your-agency)
├── Child Tenant: client-a
├── Child Tenant: client-b
├── Child Tenant: client-c
└── ...
```

Each child tenant is completely independent:

* Separate corpus
* Separate conversations
* Distinct settings
* Consolidated billing on parent

## Use cases

### Digital agency

Manage all your clients' chatbots from a single dashboard.

### Franchise

Each franchisee has their personalized chatbot, you keep central control.

### Multi-brand

A company with multiple brands, each with its own chatbot.

### B2B SaaS

Offer a chatbot to each of your enterprise clients.

## Creating a Child Tenant

### Via the Dashboard

1. **Dashboard > Tenants > Create tenant**
2. Fill in:
   * Unique slug (`client-x`)
   * Display name
   * Plan (inherited or specific)
3. Save

### Via the API

```bash theme={null}
curl -X POST https://api.animam.ai/tenants \
  -H "Authorization: Bearer ak_parent_token" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "client-x",
    "name": "Client X",
    "parentId": "parent_tenant_id"
  }'
```

## Access management

### Parent administrator

Full access to all child tenants:

* View/modify corpus
* View conversations
* Modify settings
* Create/delete tenants

### Child administrator

Limited access to their tenant:

* Manage their corpus
* View their conversations
* Modify their settings
* No access to other tenants

### Creating a child admin

```bash theme={null}
curl -X POST https://api.animam.ai/tenants/client-x/users \
  -H "Authorization: Bearer ak_parent_token" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@client-x.com",
    "role": "admin"
  }'
```

## Multi-Tenant API

### List child tenants

```bash theme={null}
curl https://api.animam.ai/tenants?parent=your-agency \
  -H "Authorization: Bearer ak_parent_token"
```

### Access a child tenant

Use the child's slug:

```bash theme={null}
# Child tenant corpus
curl https://api.animam.ai/tenants/client-x/corpus \
  -H "Authorization: Bearer ak_parent_token"
```

### Tenant-scoped token

Create tokens limited to a child tenant:

```bash theme={null}
curl -X POST https://api.animam.ai/tenants/your-agency/tokens \
  -H "Authorization: Bearer ak_parent_token" \
  -d '{
    "name": "Client X API",
    "scopes": ["corpus:read", "corpus:write"],
    "tenantScope": "client-x"
  }'
```

## Billing

### Consolidated (default)

All child tenants billed to parent account:

* Single invoice
* Total volume = sum of children
* Volume discounts available

### Separate (optional)

Each child tenant can have their own billing:

* Useful for client rebilling
* Stripe Connect supported

## Limits by plan

| Plan        | Child Tenants       | Total messages/month |
| ----------- | ------------------- | -------------------- |
| Pro         | 1 (no multi-tenant) | 10,000               |
| Enterprise  | 10 included         | 100,000              |
| Enterprise+ | Unlimited           | Custom               |

## Best practices

### Slug naming

Use a consistent prefix:

```
agency-clienta
agency-clientb
agency-clientc
```

### Environment separation

```
prod-clienta  # Production
staging-clienta  # Staging/Test
```

### Monitoring

Monitor metrics per tenant:

```bash theme={null}
curl https://api.animam.ai/tenants/your-agency/stats?groupBy=child \
  -H "Authorization: Bearer ak_parent_token"
```

## Corpus templates

Create reusable templates:

1. **Dashboard > Templates > Create**
2. Define base corpus
3. Apply to new child tenant

```bash theme={null}
curl -X POST https://api.animam.ai/tenants/new-client/corpus/apply-template \
  -H "Authorization: Bearer ak_parent_token" \
  -d '{"templateId": "template_ecommerce"}'
```

## Support

For Enterprise multi-tenant questions:

* Email: [enterprise@animam.ai](mailto:enterprise@animam.ai)
* Dedicated Slack (Enterprise+)