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

# Multi-Tenancy e Sub-Tenants

> Entenda como o Triglit fornece multi-tenancy aos seus clientes através de sub-tenants

O **Triglit** é uma plataforma multi-tenant que aceita múltiplos clientes. Além disso, o Triglit **fornece multi-tenancy** aos seus clientes, permitindo que cada cliente (tenant) tenha seus próprios clientes segmentados através de **sub-tenants**.

## Hierarquia de Organização

```
Triglit (Plataforma)
├── Tenant A (Cliente do Triglit)
│   ├── Sub-Tenant A1 (Cliente do Tenant A)
│   ├── Sub-Tenant A2 (Cliente do Tenant A)
│   └── Sub-Tenant A3 (Cliente do Tenant A)
├── Tenant B (Cliente do Triglit)
│   ├── Sub-Tenant B1 (Cliente do Tenant B)
│   └── Sub-Tenant B2 (Cliente do Tenant B)
└── Tenant C (Cliente do Triglit)
    └── (sem sub-tenants)
```

## Conceitos Fundamentais

### Tenant (Cliente do Triglit)

Um **tenant** é um cliente do Triglit. Cada tenant:

* Tem suas próprias chaves de API (pública e secreta)
* Possui isolamento completo de dados e configurações
* Pode ter múltiplos sub-tenants
* É identificado pelo `tenantId` em todas as requisições da API

<Note>
  O `tenantId` é automaticamente identificado a partir da chave de API utilizada. Você não precisa enviar este parâmetro explicitamente.
</Note>

### Sub-Tenant (Cliente do Cliente)

Um **sub-tenant** é um cliente do seu cliente (tenant). Permite que você:

* Organize workflows por cliente final
* Isole dados e execuções por cliente final
* Gerencie métricas e auditoria separadamente
* Ofereça multi-tenancy aos seus próprios clientes

<Note>
  O `subTenantId` é opcional. Workflows podem existir no nível do tenant (sem sub-tenant) ou associados a um sub-tenant específico.
</Note>

## Por que usar Sub-Tenants?

<AccordionGroup>
  <Accordion title="Segmentação por Cliente Final">
    Quando você oferece o Triglit aos seus clientes, cada cliente final pode ser um sub-tenant, garantindo isolamento completo de dados.
  </Accordion>

  <Accordion title="Organização por Departamento">
    Separe workflows de diferentes departamentos (Vendas, Suporte, Marketing) dentro do mesmo tenant.
  </Accordion>

  <Accordion title="Isolamento de Execuções">
    Execuções (runs) são isoladas por sub-tenant, permitindo rastreabilidade e métricas separadas.
  </Accordion>

  <Accordion title="Métricas e Auditoria">
    Acompanhe métricas e logs separadamente por sub-tenant para cada cliente final.
  </Accordion>
</AccordionGroup>

## Identificação na API

### Tenant ID

O `tenantId` identifica **seu cliente no Triglit**:

* Identificado automaticamente a partir da chave de API
* Não precisa ser enviado explicitamente
* Todos os recursos pertencem a um tenant específico

### Sub-Tenant ID

O `subTenantId` identifica **um cliente do seu cliente**:

* Opcional em todas as requisições
* Quando fornecido, filtra/associa recursos ao sub-tenant
* Permite segmentação adicional dentro do tenant

## Criando Sub-Tenants

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.triglit.com/v1/gateway/sub-tenants" \
    -H "X-API-Key: sk_sua_chave" \
    -H "Content-Type: application/json" \
    -d '{
      "subTenantId": "cliente-final-123",
      "name": "Cliente Final ABC",
      "description": "Cliente corporativo da empresa ABC"
    }'
  ```

  ```javascript JavaScript theme={null}
  import Triglit from 'triglit';

  const client = new Triglit({ apiKey: 'sk_sua_chave' });
  const subTenant = await client.subTenants.create({
    subTenantId: 'cliente-final-123',
    name: 'Cliente Final ABC',
    description: 'Cliente corporativo da empresa ABC'
  });
  ```

  ```python Python theme={null}
  import requests

  headers = {
      'X-API-Key': 'sk_sua_chave',
      'Content-Type': 'application/json'
  }

  data = {
      'subTenantId': 'cliente-final-123',
      'name': 'Cliente Final ABC',
      'description': 'Cliente corporativo da empresa ABC'
  }

  response = requests.post(
      'https://api.triglit.com/v1/gateway/sub-tenants',
      headers=headers,
      json=data
  )

  subTenant = response.json()
  ```
</CodeGroup>

## Usando Sub-Tenants

### Criar Workflow para Sub-Tenant

```bash theme={null}
POST /v1/gateway/workflows
{
  "name": "Workflow Cliente ABC",
  "subTenantId": "cliente-final-123"
}
```

### Listar Workflows por Sub-Tenant

```bash theme={null}
GET /v1/gateway/workflows?subTenantId=cliente-final-123
```

### Workflows sem Sub-Tenant

Workflows podem existir no nível do tenant (sem sub-tenant):

```bash theme={null}
POST /v1/gateway/workflows
{
  "name": "Workflow Global",
  # subTenantId não especificado - workflow do tenant
}
```

## Estrutura de Dados

### Sub-Tenant

```json theme={null}
{
  "id": "sub_123",
  "tenantId": "tenant_abc",
  "subTenantId": "cliente-final-123",
  "name": "Cliente Final ABC",
  "description": "Cliente corporativo da empresa ABC",
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-01-15T10:00:00Z"
}
```

### Workflow com Sub-Tenant

```json theme={null}
{
  "id": "workflow_456",
  "tenantId": "tenant_abc",
  "subTenantId": "cliente-final-123",
  "name": "Processar Pedido Cliente ABC"
}
```

### Execução (Run) com Sub-Tenant

```json theme={null}
{
  "id": "run_789",
  "tenantId": "tenant_abc",
  "subTenantId": "cliente-final-123",
  "workflowVersionId": "version_456",
  "entityId": "order_123"
}
```

## Isolamento

### Isolamento Completo

Cada sub-tenant tem isolamento completo:

* ✅ **Workflows**: Isolados por sub-tenant
* ✅ **Execuções**: Isoladas por sub-tenant
* ✅ **Triggers**: Configurados por sub-tenant
* ✅ **Métricas**: Agregadas por sub-tenant
* ✅ **Logs**: Rastreados por sub-tenant

### Queries Sempre Filtradas

Todas as queries na API são automaticamente filtradas:

```bash theme={null}
# Retorna apenas workflows do sub-tenant especificado
GET /v1/gateway/workflows?subTenantId=cliente-final-123

# Retorna apenas workflows do tenant (sem sub-tenant)
GET /v1/gateway/workflows
```

## Listagem Combinada

Você pode listar workflows de múltiplos sub-tenants em uma única requisição:

```bash theme={null}
GET /v1/gateway/sub-tenants/combined?subTenantIds=cliente-1,cliente-2,cliente-3
```

Isso retorna workflows de todos os sub-tenants especificados.

## Casos de Uso

### Caso 1: SaaS B2B oferecendo Triglit aos clientes

```
Você (Tenant do Triglit)
└── Cliente A (Sub-Tenant)
    └── Workflows específicos do Cliente A
└── Cliente B (Sub-Tenant)
    └── Workflows específicos do Cliente B
```

### Caso 2: Organização por Departamento

```
Sua Empresa (Tenant do Triglit)
└── Departamento de Vendas (Sub-Tenant)
    └── Workflows de vendas
└── Departamento de Suporte (Sub-Tenant)
    └── Workflows de suporte
```

### Caso 3: Ambientes Separados

```
Sua Empresa (Tenant do Triglit)
└── Produção (Sub-Tenant)
    └── Workflows de produção
└── Staging (Sub-Tenant)
    └── Workflows de teste
```

## Boas Práticas

<AccordionGroup>
  <Accordion title="Nomenclatura Consistente">
    Use uma convenção de nomenclatura clara para sub-tenants: `cliente-{id}`, `dept-{nome}`, `env-{ambiente}`.
  </Accordion>

  <Accordion title="Uso Apropriado">
    Use sub-tenants quando precisar segmentar por cliente final, departamento ou ambiente. Para workflows globais, não use sub-tenant.
  </Accordion>

  <Accordion title="Documentação">
    Documente o propósito de cada sub-tenant na descrição para facilitar manutenção.
  </Accordion>

  <Accordion title="Hierarquia Clara">
    Mantenha uma hierarquia lógica e fácil de entender. Evite muitos níveis de sub-tenants.
  </Accordion>
</AccordionGroup>

## Limitações

* **Máximo de sub-tenants**: 100 por tenant (configurável)
* **Identificador único**: `subTenantId` deve ser único por tenant
* **Opcional**: Sub-tenants são opcionais, não obrigatórios

## Exemplo Completo

Vamos criar uma estrutura para uma empresa que oferece o Triglit aos seus clientes:

<CodeGroup>
  ```bash cURL theme={null}
  # 1. Criar sub-tenants para cada cliente final
  curl -X POST "https://api.triglit.com/v1/gateway/sub-tenants" \
    -H "X-API-Key: sk_sua_chave" \
    -H "Content-Type: application/json" \
    -d '{
      "subTenantId": "empresa-abc",
      "name": "Empresa ABC",
      "description": "Cliente corporativo ABC"
    }'

  curl -X POST "https://api.triglit.com/v1/gateway/sub-tenants" \
    -H "X-API-Key: sk_sua_chave" \
    -H "Content-Type: application/json" \
    -d '{
      "subTenantId": "empresa-xyz",
      "name": "Empresa XYZ",
      "description": "Cliente corporativo XYZ"
    }'

  # 2. Criar workflows para cada cliente
  curl -X POST "https://api.triglit.com/v1/gateway/workflows" \
    -H "X-API-Key: sk_sua_chave" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Processar Pedido - Empresa ABC",
      "subTenantId": "empresa-abc"
    }'

  # 3. Listar workflows de um cliente específico
  curl -X GET "https://api.triglit.com/v1/gateway/workflows?subTenantId=empresa-abc" \
    -H "X-API-Key: sk_sua_chave"
  ```

  ```javascript JavaScript theme={null}
  import Triglit from 'triglit';

  const client = new Triglit({ apiKey: 'sk_sua_chave' });

  // 1. Criar sub-tenant
  const subTenant = await client.subTenants.create({
    subTenantId: 'empresa-abc',
    name: 'Empresa ABC',
    description: 'Cliente corporativo ABC'
  });

  // 2. Criar workflow para o sub-tenant
  const workflow = await client.workflows.create({
    name: 'Processar Pedido - Empresa ABC',
    subTenantId: 'empresa-abc'
  });

  // 3. Listar workflows do sub-tenant
  const workflows = await client.workflows.list({
    subTenantId: 'empresa-abc'
  });
  ```
</CodeGroup>

## Resumo

* **Tenant**: Seu cliente no Triglit (identificado automaticamente pela chave de API)
* **Sub-Tenant**: Cliente do seu cliente (opcional, para segmentação)
* **Isolamento**: Completo entre tenants e sub-tenants
* **Uso**: Sub-tenants permitem oferecer multi-tenancy aos seus próprios clientes

<Tip>
  Use sub-tenants quando precisar segmentar por cliente final, departamento ou ambiente. Para workflows globais do seu tenant, não é necessário usar sub-tenants.
</Tip>