Receita — Convite por admin

Cenário: seu sistema é fechado. Só o admin concede acesso — usuários não podem se cadastrar sozinhos. O admin cria o usuário e define a senha inicial (ou envia link de reset).

---

O que acontece

Admin (Admin Console ou script)
  │
  ├─ 1. Cria usuário via POST /admin/users
  ├─ 2. Cria membership via POST /admin/memberships
  │       └─ atribui role(s) e opcionalmente profiles
  └─ 3. Envia e-mail com senha temporária ou link de reset
             │
             Usuário faz login → Auth Platform verifica membership
             → emite token com roles e account_id

---

Passo 1 — Configurar o sistema (fechado)

curl -X POST http://localhost:4000/admin/systems \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "App Corporativo",
    "redirectUris": ["https://app.empresa.com/callback"],
    "allowedScopes": ["openid","email","profile","offline_access"],
    "allowSelfRegister":      false,  # ← ninguém se cadastra sozinho
    "requireAdminActivation": true,   # ← memberships criadas como pending por padrão
    "requireEmailOtp":        false,
    "requireMfa":             false
  }'

---

Passo 2 — Criar usuário

# Via Admin Console: Usuários → Novo usuário
# Via API:
USER=$(curl -s -X POST http://localhost:4000/admin/users \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email":         "joao@empresa.com",
    "password":      "Senha@Temp123",
    "emailVerified": true
  }')
USER_ID=$(echo $USER | jq -r '.id')
echo "Usuário criado: $USER_ID"

---

Passo 3 — Conceder acesso

# Buscar role para atribuir
ROLES=$(curl -s http://localhost:4000/admin/systems/$SYSTEM_ID/roles \
  -H "Authorization: Bearer $ADMIN_TOKEN")
MEMBER_ROLE_ID=$(echo $ROLES | jq -r '.[] | select(.name=="member") | .id')

# Criar membership — systemId cria a Account automaticamente
curl -X POST http://localhost:4000/admin/memberships \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"userId\":   \"$USER_ID\",
    \"systemId\": \"$SYSTEM_ID\",
    \"roles\":    [\"$MEMBER_ROLE_ID\"],
    \"status\":   \"active\"
  }"

Dica: se o sistema tem requireAdminActivation: true, a membership é criada como pending. Aprove com PATCH /admin/memberships/:id { "status": "active" }.

---

Passo 4 — Enviar credenciais ao usuário

Opção A — Senha temporária gerada

RESET=$(curl -s -X POST http://localhost:4000/admin/users/$USER_ID/reset-password \
  -H "Authorization: Bearer $ADMIN_TOKEN")
TEMP_PASS=$(echo $RESET | jq -r '.temporaryPassword')

echo "Envie para o usuário:"
echo "  E-mail: joao@empresa.com"
echo "  Senha temporária: $TEMP_PASS"
# Envie por canal seguro (e-mail, chat, etc.)

Opção B — Link de reset de senha

# Dispara o e-mail de reset automaticamente via EmailService
curl -X POST http://localhost:4000/admin/users/$USER_ID/send-password-reset \
  -H "Authorization: Bearer $ADMIN_TOKEN"
# → usuário recebe e-mail com link válido por 30 minutos

---

Passo 5 — Aprovar memberships em lote (script)

# examples/07-admin-api/aprovar-pendentes.sh
export ADMIN_TOKEN="..."
export AUTH_URL="http://localhost:4000"
export SYSTEM_ID="..."

# Lista memberships pendentes
PENDING=$(curl -s "$AUTH_URL/admin/memberships?status=pending&systemId=$SYSTEM_ID" \
  -H "Authorization: Bearer $ADMIN_TOKEN")

# Aprova cada uma
echo $PENDING | jq -r '.data[].id' | while read MB_ID; do
  curl -s -X PATCH "$AUTH_URL/admin/memberships/$MB_ID" \
    -H "Authorization: Bearer $ADMIN_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"status":"active"}'
  echo "Aprovado: $MB_ID"
done

---

Passo 6 — Revogar acesso

# Bloquear temporariamente (usuário não consegue logar)
curl -X PATCH http://localhost:4000/admin/memberships/$MEMBERSHIP_ID \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status":"blocked"}'

# Remover permanentemente
curl -X DELETE http://localhost:4000/admin/memberships/$MEMBERSHIP_ID \
  -H "Authorization: Bearer $ADMIN_TOKEN"
# → emite webhook user.access_revoked

---

Automação via código (Node.js)

const AUTH_URL = 'http://localhost:4000';

async function inviteUser(adminToken: string, systemId: string, email: string, roleId: string) {
  // 1. Criar usuário
  const userRes = await fetch(`${AUTH_URL}/admin/users`, {
    method:  'POST',
    headers: { Authorization: `Bearer ${adminToken}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({ email, emailVerified: true }),
  });
  const user = await userRes.json() as any;

  // 2. Gerar senha temporária
  const resetRes = await fetch(`${AUTH_URL}/admin/users/${user.id}/reset-password`, {
    method:  'POST',
    headers: { Authorization: `Bearer ${adminToken}` },
  });
  const { temporaryPassword } = await resetRes.json() as any;

  // 3. Criar membership ativa
  await fetch(`${AUTH_URL}/admin/memberships`, {
    method:  'POST',
    headers: { Authorization: `Bearer ${adminToken}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({ userId: user.id, systemId, roles: [roleId] }),
  });

  return { userId: user.id, email, temporaryPassword };
}

---

Checklist

• Sistema com allowSelfRegister: false
• Role padrão criada para novos membros
• Processo definido para comunicar credenciais ao usuário
• Webhook configurado para notificações de acesso
• Script de aprovação em lote para onboarding em massa

Scripts prontos: examples/07-admin-api/gerenciar-acesso.sh e aprovar-pendentes.sh