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

# Migrando um app existente para o Clerk Auth

> Melhores práticas para migrar um app existente com sua própria autenticação para o Clerk Auth sem perder contas de usuário ou dados históricos.

Se seu app já tem um sistema de autenticação funcionando e um banco de dados de usuários reais, trocar para o [Clerk Auth](/pt/references/auth-and-identity/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 estranha ao Clerk: novas contas são provisionadas no primeiro login, nenhuma delas se alinha com seus dados históricos, e os clientes que retornam parecem ter "perdido" suas contas.

Há realmente apenas duas coisas que você precisa acertar.

<Note>
  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. **Não** é um guia para mover um app do [Replit Auth](/pt/references/auth-and-identity/authentication) para o Clerk Auth — orientações oficiais para esse caminho de migração estão por vir.

  Se você está começando um novo app, veja a [visão geral do Clerk Auth](/pt/references/auth-and-identity/clerk-auth) — nenhuma migração é necessária.
</Note>

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

Cada usuário ativo no seu app precisa existir como usuário Clerk *antes* do Clerk Auth entrar em funcionamento. No mínimo, cada importação precisa incluir:

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

O hasher é a parte mais fácil de errar. O Clerk aceita apenas 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 requer na [referência da API Create User do Clerk](https://clerk.com/docs/reference/backend/user/create-user).

Esta etapa requer mais do que um prompt de uma linha. O Agent que conduz a migração precisa de uma **compreensão completa de como as senhas são hasheadas na sua base de código atual** — qual biblioteca, quais parâmetros (fator de custo, layout de salt, pepper, etc.) e como isso se mapeia em 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 hasheadas (biblioteca, algoritmo, parâmetros e como o valor armazenado é formatado).
Em seguida, escreva um script de importação único que, para cada usuário na minha
tabela de usuários, chame a API Backend do Clerk com email, metadados de perfil,
o digest de senha no formato exato que o hasher Clerk correspondente espera, e o
valor correto de `passwordHasher`. Diga-me qual hasher Clerk você escolheu e por quê
antes de executá-lo.
```

Se seu esquema de hash não se mapeia claramente para nenhum dos hashers suportados pelo Clerk, os usuários importados não conseguirão fazer login com sua senha existente. Nesse caso, importe-os sem um digest e envie um email de redefinição de senha no momento da migração.

## 2. Resolva usuários Clerk de volta para seus IDs de usuário existentes

Depois que os usuários importados fizerem login, cada requisição autenticada carrega uma identidade Clerk. Seu servidor precisa mapear essa identidade de volta para a linha na sua tabela `users` — caso contrário, o ID de usuário Clerk não 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 torna isso simples: quando você importa um usuário com seu ID existente como `externalId` do usuário Clerk, esse valor é automaticamente escrito nas claims da sessão como `sessionClaims.userId`. Seu middleware só precisa preferir esse valor sobre o ID de usuário Clerk bruto:

```ts theme={null}
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 este padrão:

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

## É isso

Todo o resto — manter sua autenticação antiga funcionando em paralelo, executar um teste com contas reais, monitorar a criação de usuários duplicados após a migração, 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](/pt/references/auth-and-identity/clerk-auth) — Como o Clerk Auth funciona no Replit
* [Clerk: Create User API](https://clerk.com/docs/reference/backend/user/create-user) — Hashers de senha suportados e formatos de digest