> ## 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.

# Migrating an existing app to 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 o seu app já tem um sistema de autenticação funcionando e um banco de dados de usuários reais, trocar pelo [Clerk Auth](/core-concepts/project-editor/auth-and-security/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 tornará estranha ao Clerk: novas contas são provisionadas no primeiro login, nenhuma delas corresponde aos seus dados históricos, e clientes que retornam parecem ter "perdido" suas contas.

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

<Note>
  Esta página é para desenvolvedores que já rodam um app com sua própria autenticação. Se você está começando um novo app, consulte a [visão geral do Clerk Auth](/core-concepts/project-editor/auth-and-security/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 um usuário Clerk *antes* do Clerk Auth entrar em operaçã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
* **Hash de senha**: o hash de senha existente do usuário
* **Algoritmo de hash**: o algoritmo/formato desse hash, exatamente como o Clerk espera

O algoritmo de hash é a parte que é 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 de Criação de Usuário 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 profunda de como as senhas são hasheadas no seu código atual** — qual biblioteca, quais parâmetros (fator de custo, layout de salt, pepper, etc.) e como isso mapeia para um dos algoritmos 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 users,
chame a API Backend do Clerk com e-mail, metadados de perfil, o digest de senha no formato
exato que o algoritmo Clerk correspondente espera, e o valor correto de `passwordHasher`.
Diga-me qual algoritmo Clerk você escolheu e por quê antes de executar.
```

Se o seu esquema de hash não mapear claramente para nenhum dos algoritmos 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 e-mail de redefinição de senha na transição.

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

Uma vez que os usuários importados fazem login, cada solicitaçã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 do 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 pela Replit torna isso simples: quando você importa um usuário com seu ID existente como o `externalId` do usuário Clerk, esse valor é automaticamente escrito nas claims da sessão como `sessionClaims.userId`. Seu middleware só precisa preferir isso em vez do ID de usuário bruto do Clerk:

```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 esse padrão:

* **Usuários importados** resolvem para seu `users.id` existente via `sessionClaims.userId` — todos os seus dados históricos permanecem vinculados.
* **Usuários novos** (que se cadastraram após a transição e não têm `externalId`) recorrem a `auth.userId`, que é seu ID de usuário do Clerk. Use o ID de usuário do 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 rodando em paralelo, executar um teste com contas reais, monitorar a criação de usuários duplicados após a transiçã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](/core-concepts/project-editor/auth-and-security/clerk-auth) — Como o Clerk Auth funciona no Replit
* [Clerk: API de Criação de Usuário](https://clerk.com/docs/reference/backend/user/create-user) — Algoritmos de hash de senha e formatos de digest suportados