Controle de acesso
Escolha como os leitores acessam sua documentação: totalmente pública, protegida por senha, mista (públicas e privadas), com login próprio via JWT ou SSO. Escolha a que melhor atende seu público.
A Jamdesk oferece cinco formas de controlar quem pode ler sua documentação.
Escolha a abordagem certa
| Abordagem | Use quando | Configuração |
|---|---|---|
| Totalmente pública | Documentação de produto voltada ao público externo, projetos de código aberto, qualquer conteúdo que você queira indexado e compartilhável. | Padrão. Não exige configuração. |
| Senha para o site inteiro | Tudo é interno: runbooks de engenharia, documentação exclusiva para parceiros, um produto não lançado. Uma senha compartilhada protege o site inteiro. | auth.password.enabled: true em docs.json + defina a senha no dashboard. Veja Proteção por senha. |
| Mista (algumas páginas privadas) | A maior parte da documentação é pública. Algumas poucas são internas (um runbook, um recurso beta, uma referência de API interna). | Adicione private: true ao frontmatter das páginas internas, ou liste-as em auth.password.private[]. Veja Proteção por senha. |
| Login próprio (JWT) | Os leitores já fazem login no seu produto. Seu backend assina um token de curta duração para cada leitor, e a Jamdesk o transforma em uma sessão. As páginas podem ser restritas aos grupos que você indicar no token. | auth.jwt.enabled: true mais um loginUrl em docs.json, e uma chave de assinatura gerada no dashboard. Incluído em todos os planos. Veja Autenticação JWT. |
| SSO (Enterprise) | Os leitores devem entrar com seu provedor de identidade existente: sem senhas compartilhadas, com trilha de auditoria e desprovisionamento ao remover o usuário. | Plano Enterprise. Veja SSO. |
Troque de abordagem a qualquer momento editando docs.json e enviando as alterações. Trocar de site inteiro para misto (ou o inverso) exige apenas um build.
Padrões comuns
Documentação interna e externa no mesmo projeto
Você não precisa de dois projetos para ter documentação interna atrás de um login e um site público para clientes. Use o modo misto em um único projeto da Jamdesk:
---
title: Incident Runbook
private: true
---
Páginas com private: true ficam protegidas. Todo o restante continua público. Você mantém um repositório, um build e um dashboard. A tela de desbloqueio aparece apenas em páginas protegidas.
Para seções internas maiores, liste os caminhos em docs.json em vez de marcar cada arquivo. auth.password.private[] ativa automaticamente o modo de páginas específicas. Não adicione enabled: true junto com ele, pois isso ativaria o modo de site inteiro, o oposto do que você quer aqui.
{
"auth": {
"password": {
"hint": "Ask the on-call engineer",
"private": ["/internal/**", "/admin/runbook"]
}
}
}Dois projetos separados
Use dois projetos apenas quando os públicos precisarem de identidades visuais totalmente diferentes, domínios personalizados separados, análises separadas ou planos diferentes. Exemplos: um site de documentação público em docs.acme.com e uma wiki interna separada em internal.acme.com. O custo de manutenção é maior: dois builds, dois dashboards, dois domínios.
Acesso por usuário usando seu próprio login
Uma senha compartilhada é um retrocesso quando seus clientes já têm contas com você. Ela é repassada, nunca expira sozinha e não consegue diferenciar um cliente de outro. A autenticação JWT envia um leitor já autenticado que abre sua documentação para uma URL do seu lado. Seu backend assina um token, e a Jamdesk cria uma sessão para aquele leitor. Os leitores não precisam de conta na Jamdesk. Não há segredo compartilhado para ser repassado.
O token também pode carregar grupos. Adicione groups: ["admin"] ao frontmatter de uma página. Somente visitantes cujo token liste admin podem abri-la ou vê-la na navegação. Os demais recebem um 404, e a página não revela que existe.
---
title: Enterprise audit log API
groups: ["enterprise"]
---
Combine isso com caminhos public para as partes do site que devem continuar abertas, como um changelog ou uma página de status.
SSO para o site de documentação
Leitores dos planos Enterprise entram com seu provedor de identidade (Okta, Google Workspace, Azure AD etc.) em vez de digitar uma senha compartilhada. Use quando precisar de uma trilha de auditoria de quem leu o quê, ou quando o desligamento de um colaborador precisar revogar o acesso à documentação imediatamente. Veja SSO para uma visão geral e como entrar em contato com o time comercial.
Editores e leitores
A Jamdesk tem três papéis de acesso distintos:
| Papel | O que fazem | Como o acesso é concedido |
|---|---|---|
| Editores | Escrevem e atualizam o conteúdo MDX. | A documentação é editada fazendo commit de MDX no seu repositório GitHub conectado. As permissões do seu repositório GitHub decidem quem pode fazer commits. Um push só gera build se quem fez o push for membro do projeto Jamdesk (identificado pela conta GitHub vinculada ou pelo e-mail) ou por uma conta de automação que você tenha autorizado. Um push de qualquer outra pessoa aparece como build com falha. O proprietário do projeto recebe um e-mail. Veja GitHub. |
| Leitores | Visualizam o site de documentação publicado. | Todos (público), qualquer pessoa com a senha (modo senha), qualquer pessoa para quem o seu fluxo de login gere um token (JWT), ou qualquer pessoa autenticada pelo seu IdP (SSO). |
| Membros da equipe no dashboard | Gerenciam builds, análises e configurações do projeto no dashboard da Jamdesk. | Convidados em Configurações do projeto → Membros no dashboard. Ser membro também permite que os push de uma pessoa gerem build. Veja Membros da equipe. |
Um colaborador pode ter qualquer combinação desses papéis. Uma regra os conecta: os push de um editor só geram build se o editor também for membro da equipe.
