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

# Autenticação e Controle de Acesso

> Gestão de sessão, RBAC, ciclo de vida de chaves de API, política de senhas e MFA para workspaces Switchbord.

## Integração com Supabase Auth

A Switchbord usa o Supabase Auth como sua base de autenticação. Todas as sessões de usuário são gerenciadas por meio do sistema de sessão baseado em JWT do Supabase, com validação no servidor em cada requisição de API.

<Note>
  A autenticação é aplicada no nível da rota de API. Toda rota começa com a validação de sessão antes da execução de qualquer lógica de negócio.
</Note>

## Gestão de Sessão

### Janela de Tempo da Sessão

As sessões estão sujeitas a dois controles independentes de expiração:

| Controle                    | Valor   | Descrição                                              |
| --------------------------- | ------- | ------------------------------------------------------ |
| Tempo limite absoluto       | 8 horas | A sessão expira após 8h independentemente da atividade |
| Tempo limite de inatividade | 1 hora  | A sessão expira se não houver atividade por 1h         |

Esses limites são configurados no Supabase e aplicados no servidor — estendê-los requer uma alteração de configuração administrativa, e não uma solução alternativa do lado do cliente.

### Revogação de Sessão na Remoção de Membro

Quando um membro do workspace é removido, suas sessões ativas são imediatamente invalidadas em todos os dispositivos:

```typescript theme={null}
// Chamado durante a remoção de membro do workspace
await supabaseAdmin.auth.admin.signOut(userId, 'global');
```

O escopo `'global'` garante que todas as sessões do usuário sejam encerradas — não apenas a atual. Isso impede que um membro removido continue usando uma sessão existente após perder o acesso ao workspace.

## Política de Senhas

A Switchbord impõe os seguintes requisitos de senha, configurados no Supabase:

* Mínimo de **12 caracteres**
* Ao menos uma **letra maiúscula**
* Ao menos um **dígito**
* Aplicado no cadastro e na alteração de senha

<Tip>
  Recomenda-se que os usuários utilizem um gerenciador de senhas e gerem senhas únicas para cada serviço.
</Tip>

## Autenticação Multifator

O MFA TOTP (Time-based One-Time Password) do Supabase está disponível para todos os usuários. Os usuários podem cadastrar um aplicativo autenticador a partir das configurações da sua conta.

<Warning>
  A **aplicação obrigatória** do MFA (exigir MFA para todos os membros do workspace) está atualmente **planejada** e acompanhada no roadmap. Até que a aplicação obrigatória seja implementada, o MFA é opcional (opt-in) por usuário. Organizações com requisitos rigorosos de conformidade devem instruir seus membros a se cadastrarem.
</Warning>

## Controle de Acesso Baseado em Papéis (RBAC)

A Switchbord implementa quatro papéis com níveis de permissão distintos. A atribuição de papéis é gerenciada por owners e admins do workspace.

### Hierarquia de Papéis

| Papel         | Descrição                                                                                   |
| ------------- | ------------------------------------------------------------------------------------------- |
| **owner**     | Controle total do workspace, incluindo faturamento, exclusão e transferência de propriedade |
| **admin**     | Controle operacional total, incluindo gestão de membros e todas as configurações            |
| **developer** | Acesso à API, configuração de integrações, configurações técnicas                           |
| **operator**  | Operações do dia a dia: conversas, contatos, envio de mensagens                             |

### Aplicação de Papéis

As verificações de papel são realizadas em cada rota de API após a resolução do contexto de workspace:

```typescript theme={null}
export async function DELETE(req: NextRequest) {
  // Primeiro: estabelece o workspace e o papel a partir do usuário autenticado
  const { workspaceId, role } = await requireSettingsAccess(req, ['owner', 'admin']);
  // Somente owners e admins chegam a este ponto
  // ...
}
```

A lista de papéis passada para `requireSettingsAccess` define os papéis mínimos exigidos. Rotas cujo papel não esteja na lista receberão uma resposta 403.

### Referência de Capacidades por Papel

| Capacidade                     | operator | developer | admin | owner |
| ------------------------------ | -------- | --------- | ----- | ----- |
| Ver conversas                  | ✅        | ✅         | ✅     | ✅     |
| Enviar mensagens               | ✅        | ✅         | ✅     | ✅     |
| Gerenciar contatos             | ✅        | ✅         | ✅     | ✅     |
| Configurar integrações         | ❌        | ✅         | ✅     | ✅     |
| Gerenciar chaves de API        | ❌        | ✅         | ✅     | ✅     |
| Gerenciar membros do workspace | ❌        | ❌         | ✅     | ✅     |
| Configurar providers de IA     | ❌        | ✅         | ✅     | ✅     |
| Acessar logs de auditoria      | ❌        | ❌         | ✅     | ✅     |
| Excluir workspace              | ❌        | ❌         | ❌     | ✅     |

## Gestão de Chaves de API

### Ciclo de Vida da Chave

As chaves de API permitem o acesso programático à API da Switchbord. Cada chave é:

1. **Gerada** com um valor criptograficamente aleatório
2. **Hasheada** com SHA-256 antes do armazenamento — o texto puro é exibido uma única vez na criação
3. **Escopada** ao workspace criador — não pode ser usada para acessar outros workspaces
4. **Opcionalmente expirável** — `expires_at` é aplicado no momento da validação

```typescript theme={null}
// Criação de chave — faz o hash antes de armazenar
const rawKey = generateSecureToken();
const hashedKey = sha256(rawKey);
const keyPrefix = rawKey.slice(0, 8); // armazenado para identificação de exibição

await db.insert(apiKeys).values({
  workspaceId,
  hashedKey,
  prefix: keyPrefix,
  expiresAt: options.expiresAt ?? null,
  createdBy: userId,
});

// Retorna a chave em texto puro uma única vez — nunca armazenada novamente
return { key: rawKey, prefix: keyPrefix };
```

### Comparação com Timing Seguro

A validação de chaves de API usa `crypto.timingSafeEqual` para evitar ataques de canal lateral baseados em tempo (timing side-channel):

```typescript theme={null}
import { timingSafeEqual } from 'crypto';

function validateApiKey(providedKey: string, storedHash: string): boolean {
  const providedHash = sha256(providedKey);
  const a = Buffer.from(providedHash, 'hex');
  const b = Buffer.from(storedHash, 'hex');

  if (a.length !== b.length) return false;
  return timingSafeEqual(a, b);
}
```

### Aplicação da Expiração de Chave

Chaves com um valor `expires_at` são rejeitadas no momento da validação, mesmo que o hash corresponda:

```typescript theme={null}
if (key.expiresAt && key.expiresAt < new Date()) {
  throw new UnauthorizedError('API key has expired');
}
```

### Operações de Chave Escopadas por Workspace

Todas as operações de chave (listar, excluir, revogar) são filtradas pelo workspace resolvido do chamador:

```typescript theme={null}
// Um developer no workspace A não pode excluir chaves do workspace B
await db.delete(apiKeys)
  .where(
    and(
      eq(apiKeys.id, keyId),
      eq(apiKeys.workspaceId, workspaceId) // derivado da autenticação, não do corpo da requisição
    )
  );
```

## Mapeamento de Conformidade

| Padrão    | Controle                                           | Implementação                                                         |
| --------- | -------------------------------------------------- | --------------------------------------------------------------------- |
| ISO 27001 | A.9.2 — Gestão de acesso do usuário                | Modelo somente por convite, provisionamento baseado em papéis         |
| ISO 27001 | A.9.3 — Responsabilidades do usuário               | Política de senhas aplicada no nível da plataforma                    |
| ISO 27001 | A.9.4 — Controle de acesso a sistemas e aplicações | RBAC em cada rota de API                                              |
| ISO 27001 | A.9.4.3 — Sistema de gestão de senhas              | Mínimo de 12 caracteres, maiúscula + dígito obrigatórios              |
| HIPAA     | §164.312(d) — Autenticação de pessoa ou entidade   | Validação de sessão + autenticação por chave de API em todas as rotas |
| HIPAA     | §164.312(a)(1) — Controle de acesso                | RBAC com atribuições de papel de menor privilégio                     |
| SOC 2     | CC6.1 — Controles de acesso lógico                 | RBAC escopado por workspace, aplicado no servidor                     |
| SOC 2     | CC6.2 — Gestão de credenciais de sistema           | Hash de chave de API, exibição de prefixo, aplicação de expiração     |
| SOC 2     | CC6.3 — Acesso baseado em papéis                   | Hierarquia de quatro papéis aplicada em todas as rotas                |

<Tip>
  Para o mapeamento completo de controles de conformidade, veja a [Matriz de Conformidade](/pt-BR/security/compliance-matrix).
</Tip>