Replit Docs

Se o seu app já tem um sistema de autenticação funcionando e um banco de dados de usuários reais, trocar para o Clerk Auth não é apenas uma mudança de código, é uma migração de dados. Sem um plano deliberado, cada linha existente na sua tabela users se torna um estranho para o Clerk: novas contas são provisionadas no primeiro login, nenhuma delas se alinha com seus dados históricos, e clientes recorrentes parecem ter “perdido” a conta. Na verdade, existem apenas duas coisas que você precisa acertar.

Esta página cobre apenas a migração de uma solução de autenticação personalizada (sua própria tabela de usuários, hash de senha, sessões, etc.) para o Clerk Auth. Ela não é um guia para mover um app do Replit Auth para o Clerk Auth — orientações oficiais para esse caminho de migração estão chegando em breve.Se você está começando um novo app, veja a visão geral do Clerk Auth — nenhuma migração é necessária.

1. Importe seus usuários existentes para o Clerk

Todo usuário ativo do seu app precisa existir como um usuário do Clerk antes de o Clerk Auth entrar em produção. No mínimo, cada importação precisa incluir:

E-mail (obrigatório)
Metadados de perfil disponíveis: nome, status de verificação, qualquer outra coisa que você queira visível no painel Auth
Password digest: o hash de senha existente do usuário
Password hasher: o algoritmo/formato desse hash, exatamente como o Clerk espera

O hasher é a parte mais fácil de errar. O Clerk só aceita um conjunto definido de formatos de hash de senha, e cada um tem um identificador de string específico (bcrypt, scrypt_firebase, argon2i, pbkdf2_sha256, etc.). Veja a lista completa e o formato exato de digest que cada um exige na referência da API Create User do Clerk. Esta etapa exige mais do que um prompt de uma linha. O Agent que conduz a migração precisa de um entendimento completo de como as senhas são feitas em hash no seu código atual — qual biblioteca, quais parâmetros (fator de custo, layout do salt, pepper, etc.), e como isso se mapeia para um dos hashers suportados pelo Clerk. Um prompt bem formulado se parece com algo assim:

Leia meu código de autenticação existente e identifique exatamente como as senhas
são feitas em hash (biblioteca, algoritmo, parâmetros e como o valor armazenado é
formatado). Depois escreva um script de importação único que, para cada usuário
na minha tabela users, chame a Clerk Backend API com e-mail, metadados de perfil,
o password digest no formato exato que o hasher correspondente do Clerk espera, e
o valor correto de `passwordHasher`. Me diga qual hasher do Clerk você escolheu
e por quê antes de executá-lo.

Se o seu esquema de hash não mapear de forma limpa para nenhum dos hashers suportados pelo Clerk, os usuários importados não conseguirão fazer login com a senha existente. Nesse caso, importe-os sem um digest e envie um e-mail de redefinição de senha no momento do corte.

2. Resolva os usuários do Clerk de volta aos seus IDs de usuário existentes

Depois que os usuários importados fazem login, toda solicitação autenticada carrega uma identidade do Clerk. Seu servidor precisa mapear essa identidade de volta para a linha na sua tabela users — caso contrário, o ID de usuário do Clerk não vai corresponder a nenhuma das suas chaves estrangeiras existentes (orders.user_id, documents.owner_id, etc.) e os dados históricos parecerão perdidos. O Clerk gerenciado pelo Replit facilita isso: quando você importa um usuário com seu ID existente como o externalId do usuário do Clerk, esse valor é automaticamente escrito nas session claims como sessionClaims.userId. Seu middleware só precisa priorizá-lo em vez do ID de usuário bruto do Clerk:

import { getAuth } from "@clerk/express";

const requireAuth = (req: any, res: any, next: any) => {
  const auth = getAuth(req);
  const userId = auth?.sessionClaims?.userId || auth?.userId;
  if (!userId) {
    return res.status(401).json({ error: "Unauthorized" });
  }
  req.userId = userId;
  next();
};

Com esse padrão:

Usuários importados resolvem para o users.id existente via sessionClaims.userId — todos os seus dados históricos permanecem vinculados.
Usuários totalmente novos (que se cadastraram após o corte e não têm externalId) recorrem a auth.userId, que é o ID de usuário do Clerk. Use o ID de usuário do Clerk como a chave primária para essas novas linhas, ou crie uma linha no primeiro login e vincule-a posteriormente.

É isso

Todo o resto — manter sua autenticação antiga funcionando em paralelo, executar um dry-run com contas reais, monitorar a criação de usuários duplicados após o corte, desativar o sistema antigo — é higiene padrão de migração e não é específico do Clerk Auth.

Recursos adicionais

Visão geral do Clerk Auth — Como o Clerk Auth funciona no Replit
Clerk: Create User API — Password hashers e formatos de digest suportados

​1. Importe seus usuários existentes para o Clerk

​2. Resolva os usuários do Clerk de volta aos seus IDs de usuário existentes

​É isso

​Recursos adicionais

1. Importe seus usuários existentes para o Clerk

2. Resolva os usuários do Clerk de volta aos seus IDs de usuário existentes

É isso

Recursos adicionais