Clerk — Autenticação

O Clerk é o provedor de identidade do CRM. Gerencia login, sessões, organizações e usuários.

Papel no sistema

• Autenticação: Usuários do CRM (não clientes) se autenticam via Clerk
• Multi-tenancy: Cada organização CRM corresponde a uma org no Clerk
• Sessões: JWT com rotação automática
• Emails transacionais: Convites, reset de senha (enviados pelo próprio Clerk)

Credenciais necessárias

Variável	Origem	Uso
CLERK_SECRET_KEY	Clerk Dashboard → API Keys	Verificação de JWTs no backend
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY	Clerk Dashboard → API Keys	Frontend (build-time)
CLERK_WEBHOOK_SECRET	Clerk Dashboard → Webhooks	Verificação de webhooks Svix

Fluxo de autenticação

1. Usuário → frontend (crm.galdix.com.br)
   └── Clerk SDK autentica (email/senha)
   └── Clerk retorna JWT

2. Frontend → backend (apicrm.galdix.com.br)
   Authorization: Bearer <clerk_jwt>

3. Backend (ClerkAuthGuard):
   └── clerkClient.verifyToken(token)
   └── Extrai sub (clerkId)
   └── Busca User no banco por clerkId
   └── Se não encontrado: auto-sync com Clerk API

4. request.user = { id, email, role, organizationId, accessibleStores }

Webhooks

O Clerk envia webhooks para POST /webhooks/clerk usando Svix para assinatura.

Verificação: Headers svix-id, svix-timestamp, svix-signature validados com CLERK_WEBHOOK_SECRET.

Evento	Ação no CRM
user.created	Sync do novo usuário no banco local
user.updated	Atualiza nome/email
user.deleted	Remove do banco
invitation.revoked	Remove convite pendente
organization_membership.deleted	Remove usuário da organização

Auto-sync de usuários

Na inicialização do backend (ClerkBootstrapService), todos os membros de todas as orgs no Clerk são sincronizados com o banco local. Esse processo é não-fatal — falhas são logadas mas não impedem o boot.

Mapeamento de papéis Clerk → CRM

Papel no Clerk	Papel no CRM
org:admin	Super Admin (level 0)
org:member	Usuário padrão (level 2)

Override de organização (Super Admin)

Super Admins (level 0) podem passar o header x-org-id: {uuid} para administrar qualquer organização. Toda ação com esse header é logada automaticamente.

Endpoints relacionados

POST /users/invite          # Criar convite (cria no Clerk + banco)
POST /users/:id/reset-password  # Revoga sessões do usuário no Clerk
DELETE /users/:id           # Remove do banco + Clerk

Configuração no Clerk Dashboard

1. API Keys → copiar CLERK_SECRET_KEY e NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY
2. Webhooks → adicionar https://apicrm.galdix.com.br/webhooks/clerk
   • Eventos: user.*, invitation.revoked, organization_membership.deleted
   • Copiar o webhook secret para CLERK_WEBHOOK_SECRET
3. Sign-in URL: https://crm.galdix.com.br/sign-in
4. Sign-up URL: https://crm.galdix.com.br/sign-up