Receita — Cadastro white-label (self-register)

Cenário: seu SaaS quer que usuários se cadastrem sozinhos e já tenham acesso imediato — sem aprovação manual. O Auth Platform cria o usuário e a conta automaticamente.

---

O que acontece

Usuário acessa a tela de login do seu app
  │
  ├─ Clica "Criar conta"  (aparece quando allowSelfRegister=true)
  │
  ├─ Preenche e-mail + senha (ou usa Google)
  │
  └─ Auth Platform:
       1. Cria User (e-mail + senha hash Argon2id)
       2. Cria Account pessoal para o usuário
       3. Cria Membership com a role padrão
          - status: active   (se requireAdminActivation=false)
          - status: pending  (se requireAdminActivation=true)
       4. Emite token JWT → redirect para seu app

---

Passo 1 — Configurar o sistema

curl -X POST http://localhost:4000/admin/systems \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Meu SaaS",
    "redirectUris": ["https://meusaas.com/callback"],
    "allowedScopes": ["openid","email","profile","offline_access"],
    "allowSelfRegister":      true,   # ← usuário pode se cadastrar
    "requireAdminActivation": false,  # ← acesso imediato (sem aprovação)
    "requireEmailOtp":        true,   # ← verifica e-mail no 1º login
    "requireMfa":             false,
    "multiAccount":           false
  }'

Para exigir aprovação antes do acesso, use requireAdminActivation: true. O usuário verá "Aguardando aprovação do administrador" após o cadastro.

---

Passo 2 — Definir a role padrão

O usuário recebe a defaultRole do sistema automaticamente. Crie a role e defina como padrão:

# Criar role "user"
ROLE=$(curl -s -X POST http://localhost:4000/admin/systems/$SYSTEM_ID/roles \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"user","isAdmin":false,"scopes":["saas:read","saas:write"]}')
ROLE_ID=$(echo $ROLE | jq -r '.id')

# Definir como role padrão
curl -X PATCH http://localhost:4000/admin/systems/$SYSTEM_ID \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"defaultRoleId\": \"$ROLE_ID\"}"

---

Passo 3 — Integrar no frontend

Nada muda no código do seu app — o fluxo de login é idêntico. O botão "Criar conta" aparece automaticamente na tela de login do Auth Platform:

// O UserManager é configurado normalmente
const auth = new UserManager({
  authority:    'http://localhost:4000',
  client_id:    SEU_CLIENT_ID,
  redirect_uri: `${origin}/callback`,
  scope:        'openid email profile offline_access',
  response_type: 'code',
  automaticSilentRenew: true,
});

// Redireciona para a tela de login do Auth Platform
// → A tela exibe "Entrar" + "Criar conta" automaticamente
await auth.signinRedirect();

---

Passo 4 — Receber o webhook de novo acesso

Quando um usuário se cadastra, o Auth Platform emite user.access_granted:

// Seu servidor de webhooks
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  if (!verifyWebhook(req.body.toString(), req.headers['x-signature'] as string)) {
    return res.status(401).end();
  }

  const payload = JSON.parse(req.body.toString());

  if (payload.event === 'user.access_granted') {
    const { userId, accountId, roles } = payload;

    // Inicializar dados do novo usuário na sua base:
    await db.user.create({
      data: {
        authUserId: userId,
        accountId,
        plan: 'free',
        createdAt: new Date(),
      },
    });

    // Enviar e-mail de boas-vindas
    await sendWelcomeEmail(payload.userId);
  }

  res.status(200).json({ received: true });
});

---

Passo 5 — Verificação de e-mail (requireEmailOtp=true)

Se requireEmailOtp: true, o Auth Platform pede um código de 6 dígitos enviado por e-mail antes de completar o primeiro login:

1. Usuário cadastra e-mail + senha
2. Auth Platform envia código via EMAIL_PROVIDER (SMTP ou Resend)
3. Usuário digita o código na tela de verificação
4. Auth Platform marca emailVerified: true e emite o token

O único requisito: configurar EMAIL_FROM e as credenciais do provedor no .env.

---

Fluxo com requireAdminActivation=true

Se você quer aprovar manualmente antes do acesso:

Usuário cadastra → Membership criada com status=pending
                            │
                            ↓
                   Admin recebe notificação
                   (webhook user.access_granted com roles=[])
                            │
                   Admin aprova no Admin Console
                   → PATCH /admin/memberships/:id { status: "active" }
                            │
                   Auth Platform emite webhook user.access_granted
                   com roles preenchidos
                            │
                   Usuário consegue logar

---

Checklist

• Sistema com allowSelfRegister: true
• defaultRoleId definido (role que o usuário recebe ao se cadastrar)
• Webhook configurado para provisionar dados na sua base
• EMAIL_PROVIDER configurado para verificação de e-mail
• Decidir: requireAdminActivation: false (acesso imediato) ou true (aprovação manual)

Exemplo funcional: veja examples/01-nextjs-pkce com allowSelfRegister: true