Proteção por senha
Proteja sua documentação com uma senha compartilhada, para o site inteiro ou páginas específicas, sem mover nenhum conteúdo para fora do seu repositório Git.
A proteção por senha restringe documentos que ficam no Git, mas não devem ser públicos: runbooks, guias de pré-lançamento, documentação exclusiva para parceiros, recursos de acesso antecipado. Uma senha compartilhada protege o site inteiro ou um conjunto de páginas. Nada sai do seu repositório.
As capturas de tela mostram a interface em inglês.
Para autenticação por usuário, use autenticação JWT. Ela restringe sua documentação ao seu próprio sistema de login, com sessões por usuário e acesso às páginas baseado em grupos.
A proteção por senha requer um projeto Jamdesk conectado a um repositório Git. A configuração fica em docs.json e é aplicada no seu build normal.
Qual modo devo escolher?
Escolha um modo com base no que é público.
| Modo site inteiro | Modo páginas específicas | |
|---|---|---|
| Use quando | Tudo é privado: documentação interna de engenharia, uma cópia de homologação do seu site público, um produto não lançado. | A maior parte da documentação é pública. Você oculta algumas páginas (um runbook, um recurso beta, uma referência de API interna). |
| Como ativar | Defina auth.password.enabled: true em docs.json. | Marque páginas como privadas com private: true no frontmatter, ou liste caminhos em auth.password.private[]. |
| Exceções públicas | Sim: marque páginas individuais, grupos de navegação ou padrões glob como públicos. | N/A. Todas as páginas são públicas, a menos que você as marque como privadas. |
O card do dashboard, a tela de desbloqueio e os controles de rotação e revogação são os mesmos nos dois modos. Para trocar de modo, edite docs.json e envie a alteração.
Proteja o site inteiro
Declare a proteção do site inteiro em docs.json. O campo hint é opcional. É a única pista na tela que os leitores recebem sobre como obter a senha.
{
"$schema": "https://jamdesk.com/docs.json",
"name": "Acme Docs",
"theme": "jam",
"auth": {
"password": {
"enabled": true,
"hint": "Ask #docs-access on Slack"
}
}
}As dicas são texto simples, com no máximo 200 caracteres, sem HTML.
Não coloque a senha no docs.json. Defina-a no dashboard depois do build. Seu repositório guarda apenas o indicador de ativação e uma dica opcional.
Envie a alteração para a branch configurada. O build ativa a proteção por senha no modo site inteiro.
git add docs.json
git commit -m "Turn on password protection"
git pushO card do dashboard muda de Desativado para Senha não definida. O site fica bloqueado. Cada página retorna 401 e mostra a tela de senha. Nenhuma senha funciona até que você defina uma. As páginas marcadas como públicas continuam abertas. As chaves de API do projeto continuam funcionando para a API de busca, o servidor MCP, URLs .md e os arquivos llms. Para tornar o site inteiro público novamente, defina auth.password.enabled como false e envie a alteração.

Abra Configurações do projeto no dashboard e role até o card Proteção por senha. Digite uma senha (mínimo de 8 caracteres). Clique em Definir senha.
O card muda para Ativado. Visitantes sem a senha veem a tela de desbloqueio.

A Jamdesk nunca armazena sua senha em texto simples. Ela é transformada em hash com scrypt no banco de dados do dashboard e nunca é gravada no seu repositório ou no docs.json. A Jamdesk não consegue enviá-la por e-mail caso você a esqueça. Nesse caso, faça a rotação.
Abra seu site de documentação em uma janela privada do navegador (ou use curl) e confirme que aparece a tela de desbloqueio. Tente uma senha errada para verificar o estado de erro. Depois, digite a senha correta.
# Should respond with HTTP/1.1 401 and the unlock HTML
curl -I https://acme.jamdesk.app/
# Submit the password. On success, sets the jd_auth_<slug> cookie.
curl -i -X POST https://acme.jamdesk.app/jd/unlock \
-d "password=your-passphrase&from=/"Um desbloqueio bem-sucedido retorna um redirecionamento 303 com o cabeçalho Set-Cookie: jd_auth_acme=...; HttpOnly; Secure; SameSite=Lax; Max-Age=2592000. Envie esse cookie na próxima requisição.
Exceções públicas
Mantenha páginas específicas públicas enquanto o restante do site está protegido, por exemplo uma página inicial de marketing ou um formulário de cadastro.
Marque uma página como pública de três formas. O build combina todas em uma única lista de permissões.
Frontmatter é a opção mais granular. Adicione public: true a um arquivo .mdx para tornar essa página pública:
---
title: Get started
public: true
---
Grupos de navegação cobrem uma seção inteira. Defina public: true em um group ou tab da navegação do seu docs.json para tornar públicas todas as páginas abaixo dele. Por exemplo, uma aba "Marketing" ao lado da documentação interna privada:
{
"navigation": {
"tabs": [
{
"tab": "Marketing",
"public": true,
"groups": [
{
"group": "Overview",
"pages": ["landing", "pricing", "changelog"]
}
]
},
{
"tab": "Internal",
"groups": [
{ "group": "Runbooks", "pages": ["deploys", "oncall"] }
]
}
]
}
}Globs explícitos em auth.password.public[] cobrem o que o frontmatter e a navegação não alcançam: páginas de entrada no nível raiz, rotas geradas dinamicamente ou uma subárvore que você preferir não reescrever.
{
"auth": {
"password": {
"enabled": true,
"hint": "Ask #docs-access on Slack",
"public": [
"/landing",
"/pricing",
"/marketing/**",
"/blog/*"
]
}
}
}Os globs suportam * (um segmento de caminho) e ** (qualquer profundidade). A validação rejeita um / isolado, que desbloquearia todo o seu site. O card do dashboard mostra a lista de permissões resolvida pelo último build.
Proteja apenas algumas páginas
No modo páginas específicas, tudo é público por padrão. Você opta por proteger páginas individuais.
Adicione private: true ao frontmatter da página.
---
title: Incident Runbook
description: What to do when the deploys dashboard is on fire.
private: true
---Para manter a lista de caminhos protegidos em um único arquivo, adicione-os em auth.password.private[] no docs.json. As duas abordagens são cumulativas.
{
"auth": {
"password": {
"hint": "Ask the on-call engineer",
"private": ["/admin/runbook", "/internal/api-keys"]
}
}
}Não há enabled: true. Definir auth.password.private[] sem enabled ativa o modo páginas específicas.
Envie suas alterações. O próximo build ativa a proteção no modo páginas específicas. O dashboard pede que você defina uma senha.
git add content/runbook.mdx docs.json
git commit -m "Gate the incident runbook"
git pushAbra Configurações do projeto, encontre o card Proteção por senha e defina uma senha. O cabeçalho do card mostra Ativado com Páginas específicas em vez de Site inteiro. Ele lista as páginas privadas resolvidas pelo build.

Navegue pelo seu site de documentação. As páginas públicas carregam normalmente. As páginas privadas redirecionam para a tela de desbloqueio. A senha mantém você conectado por 30 dias nesse dispositivo.
O que os visitantes veem
Uma página protegida mostra um card centralizado de desbloqueio com o nome do site e uma dica opcional. Não há barra lateral nem navegação.

O card usa o logotipo e a cor primária do seu site definidos no docs.json. O campo de senha tem um botão para revelar o texto e foco automático.
Uma senha incorreta renderiza o mesmo card com uma mensagem de erro, um campo novo e um pequeno atraso entre as tentativas. Nada na página distingue "senha errada" de "nenhuma senha digitada ainda".

A senha correta define um cookie assinado. Ele vale até a sessão expirar ou até você revogá-lo.
Ferramentas de IA e chaves de API
Ferramentas que não conseguem digitar a senha, como um cliente MCP ou um script que busca o llms.txt, podem usar uma chave de API do projeto. A chave funciona para o servidor MCP, URLs de página .md e os arquivos llms. Ela nunca abre páginas HTML nem o chat de IA.
Permita que sua equipe entre com o Jamdesk
Sua equipe já tem logins no Jamdesk, então não precisa também da senha compartilhada. Adicione allowMembers e a tela de desbloqueio mostra um botão Entrar com o Jamdesk ao lado do campo de senha. Leitores externos continuam usando a senha.
{
"auth": {
"password": {
"enabled": true,
"allowMembers": true
}
}
}Essa opção vem desativada por padrão. Envie a alteração e o botão aparece após o próximo build.
Quando um membro da equipe clica em Entrar com o Jamdesk, o dashboard do Jamdesk é aberto. Se ele já estiver conectado ali, é levado de volta diretamente para a página que estava lendo. Se não estiver, faz login primeiro e depois volta para a sua documentação.
Quem pode entrar
O proprietário do projeto pode entrar, assim como qualquer pessoa adicionada como membro em Configurações → Membros no dashboard. Quem você convidar poderá ler a documentação assim que aceitar o convite.
Um membro também recebe acesso completo de editor ao projeto no dashboard. Adicione apenas pessoas em quem você confiaria para isso.
Como funcionam as sessões da equipe
Uma sessão de membro da equipe dura 14 dias. Depois disso, o membro clica no botão novamente.
Para desconectar alguém, remova essa pessoa do projeto. O acesso à documentação dela para em cerca de um minuto.
Trocar a senha compartilhada não desconecta os membros da equipe, e o mesmo vale para Revogar todas as sessões. Os logins da equipe também não afetam as sessões com senha.
Depois de conectado, um membro pode usar o chat de IA, o servidor MCP, URLs .md e o llms.txt da mesma forma que faria após digitar a senha.
Mantenha a documentação apenas para a equipe
Ative enabled e allowMembers, e não defina nenhuma senha no dashboard. A tela de desbloqueio mostra apenas o botão de entrada, então sua equipe consegue acessar e ninguém mais consegue.
Domínios e planos
O login da equipe funciona no seu subdomínio <slug>.jamdesk.app e no domínio personalizado conectado ao projeto. Isso inclui configurações de Cloudflare Worker e de subcaminho que servem sua documentação a partir do domínio personalizado. Outros aliases, como uma cópia www. do seu domínio, não são suportados. Cada host mantém sua própria sessão, então entrar em um não conecta você ao outro.
Assim como a proteção por senha, o login da equipe exige um plano pago. Se o plano do proprietário expirar, novos logins de equipe param de funcionar. Sessões já iniciadas continuam válidas até expirarem, no máximo 14 dias depois.
allowMembers se aplica apenas à proteção por senha. Sites que usam autenticação JWT não são afetados.
Troca e revogação de sessões
Abra o card Proteção por senha, digite uma nova senha no campo Rotacionar senha e clique em Salvar nova senha. A senha antiga deixa de funcionar na próxima requisição. A rotação tem efeito imediato e não exige novo build.
Para encerrar todas as sessões ativas sem trocar a senha (por exemplo, se um notebook foi perdido), clique em Revogar todas as sessões. Isso incrementa um contador de versão no servidor. Todos os cookies emitidos antes do incremento deixam de funcionar. Os visitantes precisam digitar a senha atual novamente.
Desativar a proteção
Desative a proteção editando o docs.json e enviando a alteração.
- Site inteiro: remova
auth.password.enabled(ou defina comofalse). - Páginas específicas: remova todos os marcadores
private: truee limpeauth.password.private.
O próximo build apaga o hash de senha armazenado e o card volta para Desativado. Reativar a proteção depois exige uma nova senha.
Seu repositório de origem não fica protegido por senha. A proteção por senha restringe o site de documentação hospedado em *.jamdesk.app (ou no seu domínio personalizado). Um repositório público no GitHub ainda expõe o conteúdo MDX. Torne o repositório privado para proteção completa do conteúdo.
Regras de precedência
Uma página pode corresponder a vários sinais. A ordem de resolução, do mais específico para o menos específico:
auth.password.enabled: trueprotege o site inteiro.private: truenas páginas individuais se torna redundante.- Uma página marcada com
public: trueeprivate: trueé pública. Público prevalece. public: trueno frontmatter,public: trueem grupos de navegação e globs deauth.password.public[]são combinados em uma única lista de permissões. Se qualquer sinal indicar que uma página é pública, ela é pública.auth.password.private[]semauth.password.enabledativa o modo páginas específicas.
Como funcionam as sessões e o limite de tentativas
O cookie de sessão. Após um desbloqueio bem-sucedido, a Jamdesk define um cookie chamado jd_auth_<slug> (por exemplo, jd_auth_acme). Ele é HttpOnly, Secure, SameSite=Lax, vinculado ao host e assinado com HMAC-SHA256. O payload inclui o slug do projeto, o contador de versão atual e um timestamp de expiração. Qualquer adulteração falha na validação. A duração padrão é de 30 dias, renovada a cada desbloqueio bem-sucedido.
Limite de requisições. O endpoint de desbloqueio aplica dois contadores por hora: 10 tentativas por IP e 100 tentativas por projeto. Eles são verificados antes da checagem de hash scrypt. Uma tentativa de força bruta não consome CPU nem vaza informações de tempo. Ao atingir qualquer um dos limites, a resposta é 429 Too Many Requests com o cabeçalho Retry-After.
Armazenamento. Sua senha é transformada em hash com scrypt e armazenada no Firestore do dashboard. Ela nunca chega ao seu repositório, ao seu docs.json nem a um artefato de build. Se você a perder, faça a rotação. Não existe caminho de recuperação.
Testes durante o desenvolvimento local
O jamdesk dev executa sua documentação com o conteúdo do R2 e a configuração ao vivo. A proteção por senha não é aplicada no servidor de desenvolvimento local. Você pode visualizar páginas protegidas sem a senha.
Para testar a proteção, abra o site publicado em <slug>.jamdesk.app (ou no seu domínio personalizado) em uma janela do navegador sem o cookie.
Solução de problemas
Provavelmente o card do dashboard está mostrando Senha não definida. A proteção precisa de (1) a configuração enviada no docs.json e (2) uma senha definida em Configurações do projeto. Até você definir a senha, toda requisição retorna 401 com a tela de desbloqueio como corpo da resposta.
O navegador dele tem um cookie jd_auth_<slug> antigo, de antes da rotação. Aguarde 30 dias para o cookie expirar, clique em Revogar todas as sessões no dashboard ou peça que ele limpe os cookies do domínio da documentação. Na próxima visita, ele será solicitado a digitar a senha atual.
Não diretamente. A Jamdesk usa uma senha compartilhada por site. Para acesso por grupo, separe sua documentação em múltiplos projetos (cada um com sua própria senha) ou use o modo páginas específicas com limites público/privado separados por público.
Sim. O cookie de desbloqueio é vinculado ao host. O subdomínio *.jamdesk.app e o seu domínio personalizado se autenticam de forma independente. Desbloquear um host não desbloqueia o outro.
Configurações de subcaminho (documentação em seusite.com/docs atrás do seu próprio proxy) funcionam sem ajustes. O formulário de desbloqueio é enviado sob o prefixo de caminho /_jd/. Todas as configurações de proxy documentadas já encaminham esse prefixo. Ativar ou desativar a proteção por senha não exige alterações no proxy.
Para um proxy configurado antes de o guia de configuração incluir o encaminhamento de /_jd/, adicione /_jd/* aos caminhos encaminhados.
Não. Sites protegidos definem noindex, nofollow na tela de desbloqueio e retornam 401 para cada página protegida. Os rastreadores não conseguem indexar nada atrás do bloqueio. As páginas públicas dentro de um site protegido continuam sendo indexadas.
