> ## 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.
# Clerk Auth
> Saiba como o Clerk Auth dá ao seu app Replit seu próprio sistema de autenticação dedicado com marca personalizável, contas de usuário independentes e provedores SSO.
O Clerk Auth dá ao seu app seu próprio sistema de autenticação dedicado, baseado no [Clerk](https://clerk.com). Ao contrário do [Replit Auth](/core-concepts/project-editor/auth-and-security/authentication), que usa o sistema de login da Replit e cria contas Replit, o Clerk Auth provisiona um **tenant Clerk separado** para o seu app. Os usuários do seu app criam contas diretamente no seu app — não contas Replit — e você tem controle total sobre a marca, os métodos de login e a experiência de cadastro.
**Clerk Auth vs. Replit Auth** — Com o **Clerk Auth** (esta página), seu app obtém seu próprio tenant de autenticação com marca totalmente personalizável e contas de usuário independentes da Replit. Com o **[Replit Auth](/core-concepts/project-editor/auth-and-security/authentication)**, os usuários fazem login com contas Replit e veem páginas de login com a marca Replit. Escolha o Clerk Auth quando quiser sua própria marca na experiência de login ou precisar de contas de usuário separadas da Replit.
## Clerk Auth vs. Replit Auth em resumo
| | Clerk Auth | Replit Auth |
| --------------------- | --------------------------------------------------------------------- | --------------------------------------------------------- |
| **Contas de usuário** | Os usuários criam contas no seu app (sem necessidade de conta Replit) | Os usuários fazem login com uma conta Replit |
| **Marca** | Totalmente personalizável — nome do app, ícone e cores | Página de login com marca Replit |
| **Credenciais SSO** | Traga suas próprias credenciais OAuth por provedor | Usa os apps OAuth compartilhados da Replit |
| **Ambientes** | Ambientes separados de Desenvolvimento e Produção | Ambiente único |
| **Indicações** | Sem integração com indicações Replit | Cadastros contam para as Indicações Replit |
| **Melhor para** | Apps com marca personalizada, produtos profissionais/comerciais | Configuração rápida, apps onde a marca Replit é aceitável |
## Primeiros passos
Para adicionar o Clerk Auth ao seu app, inclua-o no seu prompt do Agent:
```
Me ajude a criar um app que [sua ideia de app] e deve incluir Clerk Auth.
```
O Agent cuida de tudo — criação do tenant Clerk, armazenamento de credenciais, configuração de rotas e adição de middleware. Você não precisa de uma conta Clerk nem de nenhuma configuração manual.
## Como o Clerk Auth funciona com o Replit
Quando o Agent configura o Clerk Auth para o seu app, ele:
1. **Cria um tenant Clerk dedicado** — Seu app obtém seu próprio aplicativo Clerk com ambientes separados de Desenvolvimento e Produção
2. **Provisiona credenciais** — Chaves de API e secrets são armazenados como variáveis de ambiente
3. **Configura um proxy** — A autenticação funciona perfeitamente no seu domínio publicado
4. **Configura rotas de login e cadastro** — Componentes Clerk React pré-construídos são adicionados ao seu app
5. **Adiciona middleware do lado do servidor** — Suas rotas de API são protegidas com o middleware Express do Clerk
Você não precisa criar uma conta Clerk nem gerenciar nenhuma infraestrutura. Tudo é gerenciado automaticamente pela Replit.
## Capacidades
### O que é suportado
O Clerk Auth fornece ao seu app:
* **Contas de usuário independentes** — Os usuários do seu app não são usuários Replit; eles existem apenas no tenant Clerk do seu app
* **Páginas de login totalmente personalizadas** — Nome do app, logotipo, cores, fontes e textos nas páginas de login e cadastro são configurados no código do seu app
* **SSO com marca personalizada** — Forneça suas próprias credenciais OAuth por provedor para que a tela de consentimento OAuth do provedor exiba o nome e a marca do seu app em vez de padrões genéricos
* **Autenticação por e-mail e senha** — Cadastro e login integrados com verificação de e-mail
* **Login social (SSO)** — Permita que os usuários façam login com Google, GitHub, Apple ou X (Twitter)
* **Gerenciamento de usuários** — Visualize, pesquise e modere usuários pelo painel Auth
* **Gerenciamento de sessões** — Tokens de sessão seguros gerenciados automaticamente
* **Ambientes de Desenvolvimento e Produção** — Teste a autenticação em desenvolvimento antes de ir ao vivo
Você pode gerenciar a maior parte da configuração do Clerk Auth pela ferramenta **Auth** no Project Editor — sem necessidade de conta Clerk e sem precisar mexer no painel do Clerk.
### O que não é suportado
As seguintes capacidades não estão disponíveis no Clerk Auth hoje (em comparação com o app Clerk externo que você configura por conta própria). Confira [este FAQ](#how-does-clerk-auth-compare-to-external-clerk) para o detalhamento completo.
* **Login com número de telefone** — Login e verificação baseados em SMS
* **Suporte a MFA** — Autenticação multifator para usuários finais
* **Cobertura completa de provedores SSO** — Apenas Google, GitHub, Apple e X são suportados hoje
* **Tenants de organização** — Recursos de organização e associação de equipe do Clerk
## Ambientes de Desenvolvimento e Produção
Todo app com Clerk Auth obtém dois ambientes Clerk completamente separados: um ambiente de **Desenvolvimento** que alimenta seu app de desenvolvimento/preview enquanto você constrói, e um ambiente de **Produção** que alimenta seu app publicado. Esses ambientes são isolados por design — eles têm chaves de API separadas e armazenamentos de usuários separados.
### Chaves de API separadas
Cada ambiente tem suas próprias chaves de API publicáveis e secretas. As chaves expostas ao seu app são alternadas automaticamente dependendo se o app está rodando em desenvolvimento ou em produção:
* No seu workspace, os secrets `CLERK_PUBLISHABLE_KEY` e `CLERK_SECRET_KEY` contêm **chaves de teste** (`pk_test...` e `sk_test...`) que apontam para o ambiente de Desenvolvimento.
* Quando você publica seu app, o deploy publicado roda com **chaves ao vivo** (`pk_live...` e `sk_live...`) que apontam para o ambiente de Produção. Para verificar os prefixos, abra **Publishing → Overview → Adjust settings** e inspecione `CLERK_PUBLISHABLE_KEY` e `CLERK_SECRET_KEY`.
Você não precisa fazer nada para alternar entre ambientes — a Replit gerencia as chaves para Desenvolvimento e Produção automaticamente. Basta desenvolver, testar e publicar — está tudo pronto.
Não substitua suas chaves de teste por chaves ao vivo, não as edite no painel Secrets nem configure nada manualmente no painel do Clerk. Fazer isso quebrará a alternância automática entre desenvolvimento e produção e não é suportado com o Clerk Auth gerenciado pela Replit.
### Armazenamentos de usuários separados
Cada ambiente tem seu próprio armazenamento de usuários. Contas que se cadastram no ambiente de Desenvolvimento **não** existem no ambiente de Produção, e vice-versa:
* Um usuário que se cadastra durante os testes no app de desenvolvimento/preview é criado apenas no armazenamento de Desenvolvimento.
* Um usuário que se cadastra no seu app publicado é criado apenas no armazenamento de Produção.
* Sessões, metadados de usuário e quaisquer dados associados a um `userId` do Clerk são igualmente limitados ao ambiente em que a conta foi criada.
Esse é o comportamento esperado. Para inspecionar usuários em cada ambiente, abra o **painel Auth** no seu Workspace e use o botão de alternância de ambiente na aba **Users** para alternar entre Desenvolvimento e Produção.
O Desenvolvimento é onde você experimenta e constrói; a Produção serve os usuários reais do seu app ao vivo. Os dois são intencionalmente isolados, portanto contas e dados criados no Desenvolvimento não aparecerão na Produção.
## Gerenciando usuários
O **painel Auth** no Project Editor oferece uma visão completa dos seus usuários autenticados. Como o Clerk Auth cria um armazenamento de usuários separado para o seu app, os usuários listados aqui são contas no seu app — não contas Replit.
Na aba **Users**, você pode:
* **Ver todos os usuários** com detalhes como e-mail, nome, último login e data de criação da conta
* **Pesquisar e filtrar** para encontrar usuários específicos
* **Banir ou desbanir usuários** para controlar o acesso ao seu app
* **Ordenar usuários** por diferentes critérios
* **Alternar ambientes** — Alterne entre Desenvolvimento e Produção para gerenciar usuários em cada um
## Personalizando sua página de login
A marca visual das suas páginas de login e cadastro — nome do app, logotipo, cores, fontes e textos — é configurada no código do seu app, não no painel Auth. Para alterá-la, peça ao Agent:
```
Atualize minha página de login para usar [nome do seu app] como título, [descreva seu logotipo] e combine com as cores do meu site.
```
Por baixo dos panos, isso é controlado pelas props `appearance` e `localization` passadas para `` e o arquivo de logotipo no diretório `public/` do seu app. O Agent mantém isso sincronizado com o restante do tema do seu app.
O nome do app mostrado na **tela de consentimento do Google, Apple, GitHub ou X** (a tela que aparece depois que um usuário clica em "Fazer login com Google", etc.) é separado — vem do app OAuth registrado com aquele provedor e **não** é alterado ao editar o código da sua página de login. Para alterá-lo, configure [credenciais OAuth personalizadas](#configuring-oauth-credentials-for-an-sso-provider) para aquele provedor.
## Configurando provedores de login
O Clerk Auth suporta Google, GitHub, Apple e X como provedores de login social. Na aba **Configure** do painel Auth, você controla quais provedores aparecem na sua página de login e — na Produção — se cada provedor usa credenciais OAuth gerenciadas pela Replit ou suas próprias credenciais personalizadas para login com marca.
Abra a aba **Configure**. Na barra lateral em **SSO providers**, selecione **Development** ou **Production** — **Development** alimenta o app de desenvolvimento/preview no Workspace; **Production** alimenta seu app publicado. Cada ambiente tem sua própria lista no painel principal. A partir daí você pode:
* **Ativar ou desativar um provedor** — Use o botão para controlar se o provedor aparece na sua página de login. Provedores desativados ficam ocultos para os usuários.
* **Configurar credenciais OAuth personalizadas (somente Produção)** — Veja [Configurando credenciais OAuth para um provedor SSO](#configuring-oauth-credentials-for-an-sso-provider) abaixo.
### Configurando credenciais OAuth para um provedor SSO
Por padrão, os provedores usam **credenciais gerenciadas pela Replit** — o login funciona imediatamente, mas a tela de consentimento OAuth exibe a marca da Replit. Mude para **Custom credentials** para usar seu próprio cliente OAuth do console de desenvolvedor do provedor, de modo que a tela de consentimento exiba o nome e a marca do seu app.
1. Abra o **painel Auth** no Project Editor. Vá para a aba **Configure** e, em **SSO providers** na barra lateral, selecione **Production**.
2. Selecione o ícone **Edit** ao lado do provedor que deseja configurar. **Replit-managed credentials** está selecionado por padrão.
3. Selecione **Custom credentials**. O painel se expande para mostrar os campos de credenciais e uma lista de verificação **Provider setup** com os valores que você precisa registrar no lado do provedor.
4. Siga as instruções para concluir a configuração. As instruções contêm links diretos para o console e documentos de ajuda relevantes. Você também pode encontrar esses documentos de ajuda em [Recursos adicionais](#additional-resources) para o seu provedor.
5. Preencha todos os valores de credenciais necessários.
6. No console de desenvolvedor do provedor, registre cada entrada listada na lista de verificação **Provider setup** no portal do desenvolvedor do provedor. Use os ícones de cópia para copiar cada valor exatamente e marque os itens à medida que os concluir ou selecione **Mark all as done** quando terminar.
7. Selecione **Save changes**.
### Verificando novamente a configuração após alterações de domínio
Operações relacionadas a domínio — como vincular um novo domínio externo ou [comprar um domínio pela Replit](/cloud-services/deployments/domain-purchasing) — podem alterar as URLs de callback de redirecionamento e as origens JavaScript do seu app. Quando isso acontece, qualquer provedor configurado com credenciais personalizadas pode precisar que os novos valores sejam registrados no seu console de desenvolvedor.
Após uma alteração de domínio, retorne à aba **Configure**. Lembretes de configuração aparecem como ícones de aviso na aba, na barra lateral e ao lado dos provedores na lista **SSO providers**. Um ícone de aviso e **setup steps remaining** ao lado de um provedor significam que sua lista de verificação **Provider setup** tem novos itens a concluir.
Abra o painel de edição do provedor, copie os valores atualizados em **Provider setup**, registre-os no console de desenvolvedor do provedor e selecione **Mark all as done**.
## Configuração de domínio para verificação de e-mail
Se o seu app oferecer **cadastro por e-mail e senha**, o Clerk envia um código de verificação para a caixa de entrada de cada novo usuário. Configurar seu domínio para entrega de e-mail garante que esses códigos cheguem da URL do seu app em vez de serem atrasados ou bloqueados por filtros de spam.
### Quando você precisa dessa configuração
Você só precisa configurar registros DNS quando seu app vincula um **domínio externo gerenciado por outro provedor** (por exemplo, um domínio que você registrou na Cloudflare, GoDaddy, Namecheap ou similar).
Nenhuma configuração é necessária se o seu app for servido a partir de:
* Um subdomínio `.replit.app`
* Um domínio [comprado pela Replit](/cloud-services/deployments/domain-purchasing)
Em ambos os casos, a Replit gerencia os registros DNS por você.
### Adicionar registros DNS para envio de e-mail
Para autorizar seu app a enviar e-mails de verificação do seu domínio externo, adicione um conjunto de registros DNS no seu provedor de domínio.
1. No Project Editor, abra **Publishing**.
2. Selecione **Domains**.
3. Encontre seu domínio externo vinculado e selecione **Manage**.
4. Em **Authentication DNS setup required**, copie os registros CNAME que a Replit exibe — esses são os registros que o Clerk precisa para enviar e-mails de verificação do seu domínio.
5. Faça login no seu provedor DNS (Cloudflare, GoDaddy, Namecheap, etc.) e adicione cada registro exatamente como mostrado.
As alterações de DNS podem levar até 48 horas para se propagar. Depois que os registros estiverem ativos, o cadastro por e-mail e senha entregará códigos de verificação do seu domínio automaticamente — nenhuma ação adicional é necessária no painel Auth.
### Solução de problemas
* **E-mails de verificação não chegando** — Confirme que cada registro foi adicionado exatamente como mostrado no painel Manage, incluindo pontos finais onde seu provedor DNS exige. Verifique a pasta de spam do destinatário.
* **Registros ainda não detectados** — Aguarde a propagação do DNS (até 48 horas) e verifique novamente o painel Manage para quaisquer registros ainda sinalizados como ausentes.
## Melhores práticas de segurança
* **Sempre valide no servidor** — Verifique a autenticação nas suas rotas de API, não apenas na interface do usuário
* **Use variáveis de ambiente** — Nunca codifique chaves ou secrets no seu código
* **Mantenha o middleware de proxy em primeiro lugar** — O proxy do Clerk deve ser montado antes dos analisadores de corpo no seu app Express
* **Não redirecione a página inicial para o login** — Mantenha sua landing page acessível para visitantes não autenticados
## FAQ
### Preciso de uma conta Clerk para usar o Clerk Auth?
Não. O tenant Clerk por trás do Clerk Auth é criado e gerenciado automaticamente pela Replit quando o Agent configura seu app — você não precisa se cadastrar no Clerk nem gerenciar nenhuma infraestrutura do Clerk por conta própria.
### Posso acessar o painel do Clerk para a instância Clerk gerenciada pela Replit?
Não. A instância Clerk gerenciada pela Replit não é exposta pelo painel do Clerk. Gerencie-a pela ferramenta **Auth** no Project Editor — é lá que você configura provedores, visualiza usuários e alterna entre ambientes de Desenvolvimento e Produção.
### Minha chave publicável do Clerk começa com `pk_test`. Como faço para mudar para uma chave ao vivo?
Você não precisa. As chaves `pk_test...` e `sk_test...` que você vê no painel Secrets do workspace pertencem ao ambiente Clerk de **Desenvolvimento** do seu app e são usadas enquanto você constrói. Quando você publica seu app, o deploy roda automaticamente com as chaves `pk_live...` e `sk_live...` para o ambiente de Produção. Para verificar, abra **Publishing → Overview → Adjust settings** no seu Workspace e verifique o valor de `CLERK_PUBLISHABLE_KEY` para o app publicado — ele começará com `pk_live`. Não edite essas chaves manualmente. Consulte [Ambientes de Desenvolvimento e Produção](#development-and-production-environments) para o detalhamento completo.
### Por que não consigo fazer login no meu app publicado com a conta que criei durante o desenvolvimento?
Os ambientes de **Desenvolvimento** e **Produção** do Clerk Auth têm armazenamentos de usuários separados. Uma conta que você cria no app de desenvolvimento/preview existe apenas no ambiente de Desenvolvimento e não é copiada para a Produção quando você publica — você precisará se cadastrar novamente no app publicado. O mesmo vale para quaisquer dados associados a um `userId` do Clerk. Abra o **painel Auth** no seu Workspace e use o botão de alternância de ambiente na aba **Users** para inspecionar usuários em cada ambiente. Consulte [Armazenamentos de usuários separados](#separate-user-stores) para detalhes.
### O Clerk Auth é gratuito?
O Clerk Auth é gratuito por enquanto. Preços baseados em uso podem ser introduzidos posteriormente, em linha com outros serviços baseados em uso no Replit. Quaisquer cobranças futuras serão aplicadas por meio do seu faturamento Replit existente — você não precisará de uma fatura ou método de pagamento separado do Clerk.
### O Clerk Auth tem limite de MAU como os planos externos do Clerk?
Não. O Clerk Auth não impõe um limite de usuários ativos mensais (MAU), ao contrário dos planos externos do Clerk, que limitam os MAUs por nível.
### Como o Clerk Auth se compara ao Clerk externo?
O tenant Clerk gerenciado pela Replit por trás do Clerk Auth tem algumas nuances em comparação com apps Clerk que você cria na sua própria conta Clerk (**Clerk externo**). A tabela abaixo destaca onde os dois diferem hoje — isso reflete o estado atual do Clerk Auth, e o conjunto de recursos suportados continuará evoluindo.
| | Clerk Auth | Clerk Externo |
| ------------------------------------------ | ------------------------------------------------------------------------------ | ------------------------------ |
| **Configuração** | Provisionado automaticamente pela Replit | Configurado por conta própria |
| **Propriedade do tenant Clerk** | Gerenciado pela Replit, pertencente ao seu app | Pertencente à sua conta Clerk |
| **Estrutura de tarifas** | Atualmente gratuito (plano de ter pay-as-you-go no futuro) | Assinatura + pay-as-you-go |
| **Faturamento** | Faturamento Replit (atualmente gratuito) | Faturamento na sua conta Clerk |
| **Limite de MAU** | Ilimitado | Limitação por nível |
| **Configuração de proxy e domínio** | Automatizada para replit.app e domínio comprado, manual para domínio vinculado | Manual |
| **Provedores SSO** | Suportado em certos provedores: Google, Apple, GitHub, X | Suporta mais provedores |
| **Interface de gerenciamento de usuários** | Ferramenta Auth no Project Editor | Painel do app Clerk |
| **SMS** | Não suportado | Suportado |
| **MFA** | Não suportado | Suportado |
| **Tenants de organização** | Não suportado | Suportado |
### Quais configurações comuns do Clerk Auth preciso fazer manualmente?
A maior parte da configuração do Clerk Auth é automatizada, mas algumas configurações requerem que você tome providências fora da ferramenta **Auth**:
* **Credenciais OAuth personalizadas para provedores SSO** — Se você quiser que a tela de consentimento do provedor exiba o nome e a marca do seu app (em vez dos padrões da Replit), registre um app OAuth no console de desenvolvedor do provedor e cole as credenciais de volta no painel Auth. Consulte [Configurando credenciais OAuth para um provedor SSO](#configuring-oauth-credentials-for-an-sso-provider).
* **Registros DNS para verificação de e-mail em domínios externos** — Se o seu app vincular um domínio externo gerenciado por outro provedor, você precisará adicionar registros DNS para que e-mails de verificação sejam entregues do seu domínio. Consulte [Configuração de domínio para verificação de e-mail](#domain-setup-for-email-verification).
### Posso trazer meu próprio app Clerk em vez de usar o gerenciado pela Replit?
Sim. Se seu app já tiver um app Clerk gerenciado pela Replit provisionado, exclua-o primeiro antes de conectar seu próprio app Clerk externo:
1. Abra o painel **Auth** no Project Editor.
2. Vá para a aba **Configure**.
3. Role até o final da página e clique em **Delete Clerk app**.
Excluir o app Clerk remove o tenant Clerk gerenciado pela Replit e libera quaisquer domínios vinculados a ele, para que você possa então conectar seu próprio app Clerk e reutilizar esses domínios. Se seu app ainda não tiver um app Clerk gerenciado pela Replit, você pode pular esta etapa e integrar seu app Clerk externo diretamente.
## Recursos adicionais
* [Migrando um app existente para o Clerk Auth](/core-concepts/project-editor/auth-and-security/clerk-auth-migration) — Melhores práticas para mover um app com dados de usuários existentes para o Clerk Auth sem interromper a continuidade da conta
* [Configurar SSO do Google](/replit-workspace/whitelabel-auth/google) — Configure credenciais OAuth personalizadas do Google
* [Configurar SSO do GitHub](/replit-workspace/whitelabel-auth/github) — Configure credenciais OAuth personalizadas do GitHub
* [Configurar SSO da Apple](/replit-workspace/whitelabel-auth/apple) — Configure credenciais do Apple Sign In
* [Configurar SSO do X (Twitter)](/replit-workspace/whitelabel-auth/twitter-x) — Configure credenciais OAuth personalizadas do X
* [Documentação do Clerk](https://clerk.com/docs) — Referência para desenvolvedores integrando um app Clerk externo