Saltar para o conteúdo principal

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.

O Clerk Auth dá ao seu app seu próprio sistema de autenticação dedicado, com tecnologia do Clerk. Ao contrário do Replit Auth, que usa o sistema de login do Replit e cria contas Replit, o Clerk Auth provisiona um tenant Clerk separado para seu app. Os usuários do seu app criam contas diretamente dentro do seu app — não contas Replit — e você tem controle total sobre a marca, métodos de login e a experiência de acesso.
Clerk Auth vs. Replit Auth — Com o Clerk Auth (esta página), seu app tem seu próprio tenant de autenticação com marca totalmente personalizável e contas de usuário independentes do Replit. Com o Replit Auth, 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 do Replit.

​
Clerk Auth vs. Replit Auth em resumo

Clerk AuthReplit Auth
Contas de usuárioOs usuários criam contas dentro do seu app (sem necessidade de conta Replit)Os usuários fazem login com uma conta Replit
MarcaTotalmente personalizável — nome do seu app, ícone e coresPágina de login com marca Replit
Credenciais SSOTraga suas próprias credenciais OAuth por provedorUsa os apps OAuth compartilhados do Replit
AmbientesAmbientes de Desenvolvimento e Produção separadosAmbiente único
IndicaçõesSem integração de indicações do ReplitCadastros contam para as Indicações do Replit
Ideal paraApps com marca personalizada, produtos profissionais/comerciaisConfiguraçã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 ter o Clerk Auth.
O Agent cuida de tudo — criando o tenant Clerk, armazenando credenciais, configurando rotas e adicionando middleware. Você não precisa de uma conta Clerk ou qualquer configuração manual.

​
Como o Clerk Auth funciona com o Replit

Quando o Agent configura o Clerk Auth para seu app, ele:
  1. Cria um tenant Clerk dedicado — Seu app tem seu próprio aplicativo Clerk com ambientes de Desenvolvimento e Produção separados
  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é-criados são adicionados ao seu app
  5. Adiciona middleware no servidor — Suas rotas de API são protegidas com o middleware Express do Clerk
Você não precisa criar uma conta Clerk ou gerenciar nenhuma infraestrutura. Tudo é gerenciado automaticamente pelo 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 dentro do tenant Clerk do seu app
  • Páginas de login com marca completa — O nome do seu 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 dos padrões genéricos
  • Autenticação com email e senha — Cadastro e login integrados com verificação de email
  • Login social (SSO) — Deixe os usuários fazerem login com Google, GitHub, Apple ou X (Twitter)
  • Gerenciamento de usuários — Visualize, pesquise e modere usuários pelo painel Auth
  • Gerenciamento de sessão — Tokens de sessão seguros gerenciados automaticamente
  • Ambientes de Desenvolvimento e Produção — Teste a autenticação em desenvolvimento antes de publicar
Você pode gerenciar a maioria das configurações do Clerk Auth pela ferramenta Auth no Project Editor — sem necessidade de conta Clerk e sem precisar tocar 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). Verifique esta FAQ para o detalhamento completo.
  • Login com número de telefone — Login e verificação por 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

Cada app com Clerk Auth tem dois ambientes Clerk completamente separados: um ambiente de Desenvolvimento que alimenta seu app de desenvolvimento/preview enquanto você cria, e um ambiente de Produção que alimenta seu app publicado. Esses ambientes são isolados por design — eles têm chaves de API e armazenamentos de usuário separados.

​
Chaves de API separadas

Cada ambiente tem suas próprias chaves de API publicável e secreta. As chaves expostas ao seu app são alternadas automaticamente dependendo se o app está sendo executado em desenvolvimento ou 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.
Ferramenta Secrets no Workspace mostrando CLERK_SECRET_KEY e CLERK_PUBLISHABLE_KEY com prefixos sk_test_ e pk_test_
  • Quando você publica seu app, o deployment publicado é executado com chaves live (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.
Publishing Overview mostrando secrets do app de Produção com CLERK_SECRET_KEY e CLERK_PUBLISHABLE_KEY usando prefixos sk_live_ e pk_live_
Você não precisa fazer nada para alternar entre os ambientes — o Replit gerencia as chaves para Desenvolvimento e Produção automaticamente. Basta desenvolver, testar e publicar.
Não substitua suas chaves de teste por chaves live, 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 pelo Replit.

​
Armazenamentos de usuário separados

Cada ambiente tem seu próprio armazenamento de usuário. Contas criadas no ambiente de Desenvolvimento não existem no ambiente de Produção, e vice-versa:
  • Um usuário que se cadastra durante o teste 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 vinculados a um userId do Clerk também são limitados ao ambiente em que a conta foi criada.
Este é o comportamento esperado. Para inspecionar usuários em cada ambiente, abra o painel Auth no seu Workspace e use o toggle de ambiente na aba Users para alternar entre Desenvolvimento e Produção.
O Desenvolvimento é onde você experimenta e cria; a Produção serve os usuários reais do seu app publicado. 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ário separado para seu app, os usuários listados aqui são contas no seu app — não contas Replit.
Aba de usuários do Clerk Auth mostrando usuários autenticados no painel Auth
Na aba Users, você pode:
  • Visualizar todos os usuários com detalhes como email, 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 identidade visual da sua página 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 é impulsionado pelas props appearance e localization passadas para <ClerkProvider> e o arquivo de logotipo no diretório public/ do seu app. O Agent mantém estes em sincronia com o restante do tema do seu app.
O nome do app exibido na tela de consentimento do próprio Google, Apple, GitHub ou X (a tela que aparece após um usuário clicar em “Fazer login com o Google”, etc.) é separado — vem do app OAuth registrado naquele provedor e não é alterado editando o código da sua página de login. Para alterá-lo, configure credenciais OAuth personalizadas 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 pelo Replit ou suas próprias credenciais personalizadas para login com marca.
Aba Configure com provedores SSO na barra lateral, Produção selecionada e a lista de provedores mostrando toggles de ativação e ações de Edição
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 toggle para controlar se o provedor aparece na sua página de login. Provedores desativados ficam ocultos dos usuários.
  • Configurar credenciais OAuth personalizadas (apenas Produção) — Veja Configurando credenciais OAuth para um provedor SSO abaixo.

​
Configurando credenciais OAuth para um provedor SSO

Por padrão, os provedores usam credenciais gerenciadas pelo Replit — o login funciona imediatamente, mas a tela de consentimento OAuth mostra a marca do Replit. Mude para Credenciais personalizadas para usar seu próprio cliente OAuth do console do desenvolvedor do provedor, para que a tela de consentimento exiba o nome e a marca do seu app.
  1. Abra o painel Auth no Project Editor. Acesse a aba Configure, depois em SSO providers na barra lateral selecione Production.
  1. Selecione o ícone Edit ao lado do provedor que você deseja configurar. Credenciais gerenciadas pelo Replit são selecionadas por padrão.
Painel de edição do provedor mostrando as opções de credenciais gerenciadas pelo Replit e credenciais personalizadas
  1. Selecione Custom credentials. O painel se expande para mostrar os campos de credencial e uma lista de verificação Provider setup com os valores que você precisa registrar no lado do provedor.
Painel de credenciais personalizadas mostrando campos de ID do cliente OAuth e secret, e uma lista de verificação de configuração do provedor com URLs de callback de redirecionamento e origens JavaScript
  1. Siga as instruções para concluir a configuração. As instruções contêm links diretamente para o console e documentos de ajuda relevantes. Você também pode encontrar esses documentos de ajuda em Recursos adicionais para o seu provedor.
  2. Preencha todos os valores de credencial necessários.
  3. No console do 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 conforme os concluir ou selecione Mark all as done quando terminar.
  4. Selecione Save changes.

​
Verificar 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 pelo Replit — podem alterar as URLs de callback de redirecionamento e as origens JavaScript do seu app. Quando isso acontecer, qualquer provedor configurado com credenciais personalizadas pode precisar que os novos valores sejam registrados no console do 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 etapas de configuração pendentes ao lado de um provedor significam que sua lista de verificação Provider setup tem novos itens a concluir.
Aba Configure e barra lateral mostrando um aviso de configuração, e a lista de provedores SSO com um ícone de aviso e 'etapas de configuração pendentes' ao lado de um provedor após uma alteração de domínio
Abra o painel de edição do provedor, copie os valores atualizados em Provider setup, registre-os no console do desenvolvedor do provedor e selecione Mark all as done.

​
Configuração de domínio para verificação de email

Se seu app oferece cadastro com email 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 email 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 com Cloudflare, GoDaddy, Namecheap ou similares). Nenhuma configuração é necessária se seu app for servido a partir de: Em ambos os casos, o Replit gerencia os registros DNS para você.

​
Adicionar registros DNS para envio de email

Para autorizar seu app a enviar emails 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 o Replit exibe — estes são os registros que o Clerk precisa para enviar emails 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.
Painel Manage de domínio mostrando a seção Authentication DNS setup required com registros CNAME para entrega de email do Clerk
As alterações de DNS podem levar até 48 horas para se propagar. Assim que os registros estiverem ativos, o cadastro com email 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

  • Emails de verificação não chegando — Confirme que cada registro foi adicionado exatamente como mostrado no painel Manage, incluindo pontos finais onde necessário pelo seu provedor DNS. 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 UI
  • Use variáveis de ambiente — Nunca codifique chaves ou secrets diretamente no seu código
  • Mantenha o middleware proxy primeiro — O proxy Clerk deve ser montado antes dos parsers de body no seu app Express
  • Não redirecione a página inicial para o login — Mantenha sua landing page acessível a 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 pelo Replit quando o Agent configura seu app — você não precisa se cadastrar no Clerk nem gerenciar nenhuma infraestrutura Clerk por conta própria.

​
Posso acessar o painel do Clerk para a instância Clerk gerenciada pelo Replit?

Não. A instância Clerk gerenciada pelo 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 live?

Você não precisa fazer isso. 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ê cria. Quando você publica seu app, o deployment é executado com as chaves pk_live... e sk_live... do ambiente de Produção automaticamente. Para verificar, abra Publishing → Overview → Adjust settings no seu Workspace e verifique o valor de CLERK_PUBLISHABLE_KEY para o app publicado — começará com pk_live. Não edite essas chaves manualmente. Veja Ambientes de Desenvolvimento e Produção 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ário separados. Uma conta criada no app de desenvolvimento/preview existe apenas no ambiente de Desenvolvimento e não é copiada para Produção quando você publica — você precisará se cadastrar novamente no app publicado. O mesmo vale para quaisquer dados que você vinculou a um userId do Clerk. Abra o painel Auth no seu Workspace e use o toggle de ambiente na aba Users para inspecionar usuários em cada ambiente. Veja Armazenamentos de usuário separados para mais detalhes.

​
O Clerk Auth é gratuito?

O Clerk Auth é gratuito por enquanto. Preços baseados em uso podem ser introduzidos mais tarde, em linha com outros serviços baseados em uso no Replit. Quaisquer cobranças futuras serão aplicadas através do seu faturamento Replit existente — você não precisará de uma fatura ou método de pagamento separado do Clerk.

​
O Clerk Auth tem um 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 MAUs por tier.

​
Como o Clerk Auth se compara ao Clerk externo?

O tenant Clerk gerenciado pelo 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 AuthClerk Externo
ConfiguraçãoProvisionado automaticamente pelo ReplitConfigurado por conta própria
Propriedade do tenant ClerkGerenciado pelo Replit, pertence ao seu appPertence à sua conta Clerk
Estrutura de taxasAtualmente gratuito (plano de ter pay-as-you-go no futuro)Assinatura + pay-as-you-go
FaturamentoFaturamento Replit (atualmente gratuito)Faturamento na sua conta Clerk
Limite de MAUIlimitadoLimitação por tiers
Configuração de proxy e domínioAutomatizada para replit.app e domínio comprado, manual para domínio vinculadoManual
Provedores SSOSuportado em determinados provedores: Google, Apple, GitHub, XSuporta mais provedores
Superfície de gerenciamento de usuáriosFerramenta Auth no Project EditorPainel do app Clerk
SMSNão suportadoSuportado
MFANão suportadoSuportado
Tenants de OrgNão suportadoSuportado

​
Qual configuração comum do Clerk Auth preciso fazer manualmente?

A maior parte da configuração do Clerk Auth é automatizada, mas algumas configurações exigem que você tome medidas 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 do Replit), registre um app OAuth no console do desenvolvedor do provedor e cole as credenciais de volta no painel Auth. Veja Configurando credenciais OAuth para um provedor SSO.
  • Registros DNS para verificação de email em domínios externos — Se seu app vincula um domínio externo gerenciado por outro provedor, você precisará adicionar registros DNS para que os emails de verificação sejam entregues do seu domínio. Veja Configuração de domínio para verificação de email.

​
Posso trazer meu próprio app Clerk em vez de usar o gerenciado pelo Replit?

Sim. Se seu app já tem um app Clerk gerenciado pelo Replit provisionado, exclua-o primeiro antes de conectar seu próprio app Clerk externo:
  1. Abra o painel Auth no Project Editor.
  2. Acesse 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 pelo Replit e libera quaisquer domínios vinculados a ele, para que você possa conectar seu próprio app Clerk e reutilizar esses domínios. Se seu app ainda não tem um app Clerk gerenciado pelo Replit, você pode pular esta etapa e integrar seu app Clerk externo diretamente.

​
Recursos adicionais