Autenticação JWT

Se o seu produto já tem um sistema de login próprio, a autenticação JWT permite proteger sua documentação usando esse sistema, em vez de distribuir uma senha compartilhada. Seu backend assina um token de curta duração quando um usuário autenticado acessa a documentação. O Jamdesk o verifica uma vez, cria uma sessão e, a partir daí, o visitante navega normalmente. Os visitantes nunca precisam de uma conta Jamdesk nem de uma senha compartilhada.

Como isso difere da proteção por senha

A proteção por senha fornece a mesma senha compartilhada a todos os visitantes, o que funciona bem para documentação interna, prévias de staging ou um único público de parceiros. A autenticação JWT é por usuário: a identidade, a duração da sessão e o acesso às páginas de cada visitante vêm de um token assinado pelo seu backend. O acesso à documentação pode seguir suas contas de clientes, planos ou funções existentes, em vez de um único segredo compartilhado.

Os dois modos são mutuamente exclusivos: auth.password e auth.jwt não podem ser ativados ao mesmo tempo. Consulte Migrar da proteção por senha abaixo se estiver trocando de um para o outro.

Etapas de configuração

{
  "$schema": "https://jamdesk.com/docs.json",
  "name": "Acme Docs",
  "theme": "jam",
  "auth": {
    "jwt": {
      "enabled": true,
      "loginUrl": "https://app.example.com/docs-login",
      "public": ["/changelog/*"]
    }
  }
}

git add docs.json
git commit -m "Turn on JWT authentication"
git push

Integre seu fluxo de login

Quando um usuário autenticado acessa sua documentação, seu backend assina um JWT e redireciona o navegador para a URL de callback do site de documentação, com o token no fragmento da URL (após o #). Os fragmentos nunca chegam aos logs do servidor nem a qualquer proxy reverso, porque os navegadores não os enviam com a solicitação.

O token deve ser assinado com EdDSA (Ed25519, correspondente à chave gerada no dashboard), e sua declaração exp não deve estar mais de aproximadamente 10 segundos no futuro. Essa é uma janela de handshake, não a duração da sessão. A duração real da sessão é controlada separadamente pelo campo expiresAt no payload (consulte a referência do payload abaixo).

import { SignJWT, importPKCS8 } from "jose";

// Store this in your secret manager. It's the private key Jamdesk showed
// you once when you generated it in Project Settings.
const privateKey = await importPKCS8(process.env.JAMDESK_JWT_PRIVATE_KEY!, "EdDSA");

async function signDocsToken(user: { groups: string[] }) {
  return new SignJWT({
    host: "acme.jamdesk.app", // or your custom domain, e.g. "docs.example.com"
    expiresAt: Math.floor(Date.now() / 1000) + 60 * 60 * 24 * 7, // 7-day session
    groups: user.groups,
    apiPlaygroundInputs: {
      header: { Authorization: `Bearer ${user.apiToken}` },
    },
  })
    .setProtectedHeader({ alg: "EdDSA" })
    .setExpirationTime("10s") // handshake window, not session length
    .sign(privateKey);
}

// In your "open docs" route/button handler:
app.get("/docs-login", requireAuth, async (req, res) => {
  const token = await signDocsToken(req.user);
  const redirect = req.query.redirect ?? "/";
  res.redirect(
    `https://acme.jamdesk.app/_jd/auth/callback?redirect=${encodeURIComponent(
      String(redirect)
    )}#${token}`
  );
});

import time
import jwt  # PyJWT >= 2.4, with the cryptography extra installed

with open("jamdesk_jwt_private_key.pem", "rb") as f:
    PRIVATE_KEY = f.read()

def sign_docs_token(user):
    payload = {
        "host": "acme.jamdesk.app",  # or your custom domain
        "exp": int(time.time()) + 10,  # handshake window, not session length
        "expiresAt": int(time.time()) + 60 * 60 * 24 * 7,  # 7-day session
        "groups": user.groups,
        "apiPlaygroundInputs": {
            "header": {"Authorization": f"Bearer {user.api_token}"},
        },
    }
    return jwt.encode(payload, PRIVATE_KEY, algorithm="EdDSA")

@app.route("/docs-login")
def docs_login():
    token = sign_docs_token(current_user)
    redirect_path = request.args.get("redirect", "/")
    return redirect(
        f"https://acme.jamdesk.app/_jd/auth/callback"
        f"?redirect={quote(redirect_path)}#{token}"
    )

Fluxo de redirecionamento

1. Um visitante solicita uma página protegida (por exemplo, /quickstart) sem uma sessão válida. O Jamdesk responde com um redirecionamento para {loginUrl}?redirect=%2Fquickstart.
2. Seu fluxo de login autentica o visitante (da forma que você normalmente usa), assina um JWT e o redireciona para https://<your-docs-host>/_jd/auth/callback?redirect=%2Fquickstart#<jwt>.
3. A página de callback lê o token do fragmento no lado do cliente e o envia ao endpoint de troca de tokens do Jamdesk. O Jamdesk verifica a assinatura e as declarações e, em caso de sucesso, define um cookie de sessão assinado.
4. O navegador é redirecionado ao destino original, /quickstart, agora com uma sessão válida. O valor de redirect é preservado de ponta a ponta, para que os visitantes cheguem exatamente ao local de onde partiram.

Se o seu backend não conseguir determinar um valor de redirect (por exemplo, alguém adicionou diretamente sua página de login aos favoritos), omita-o e o Jamdesk usará /.

Páginas públicas

Algumas páginas devem permanecer acessíveis sem login, como uma página de status ou um changelog público. Há três maneiras de marcar uma página como pública, e todas são combinadas em uma única lista de permissões:

Frontmatter, uma página por vez:

---
title: Changelog
public: true
---

Grupos de navegação, para uma seção inteira:

{
  "navigation": {
    "groups": [
      { "group": "Changelog", "public": true, "pages": ["changelog"] }
    ]
  }
}

Padrões glob explícitos, em auth.jwt.public[]:

{
  "auth": {
    "jwt": {
      "enabled": true,
      "loginUrl": "https://app.example.com/docs-login",
      "public": ["/changelog/*", "/status"]
    }
  }
}

Acesso baseado em grupos

Algumas páginas devem ser visíveis apenas para determinados usuários autenticados, como um runbook de administrador ou uma referência exclusiva para empresas. Adicione groups ao frontmatter da página:

---
title: Admin API Keys
groups: ["admin"]
---

A sessão do visitante contém o array groups que seu backend incluiu no payload do JWT. Se uma página declarar groups e a sessão do visitante não tiver interseção com essa lista, ele receberá um 404, em vez de um 401 ou de uma tela de desbloqueio. Isso é intencional: uma página restrita a um grupo não revela sua própria existência a usuários de fora do grupo.

Detalhes que afetam o uso de groups:

• Páginas de grupos são excluídas do sitemap, da pesquisa, do chat de IA e do MCP, inclusive para usuários que pertencem ao grupo. A exclusão dessas superfícies de descoberta é uma decisão tomada durante o build, não por visitante. Um membro do grupo admin ainda pode abrir /admin/api-keys diretamente (pela URL ou por um link interno), mas a página não aparecerá nos resultados de pesquisa, nas respostas do chat nem em llms.txt. Se precisar que uma página restrita seja encontrada pelo próprio público, crie um link para ela em outra página que esse público já possa acessar.
• Um groups: [] vazio significa nenhuma restrição, não “ninguém pode ver isto”. Para remover a restrição de grupo de uma página, exclua o campo groups completamente, em vez de defini-lo como um array vazio.
• Para restringir uma página a ninguém, retire-a da publicação. Não há um valor de groups que signifique “ninguém”: a associação a grupos é aditiva, e qualquer sobreposição concede acesso.
• As cópias localizadas herdam automaticamente os groups da página base, a menos que a tradução declare seus próprios groups no frontmatter. Traduzir uma página restrita não torna a tradução pública acidentalmente.
• Mantenha os nomes dos grupos curtos. Os grupos são transportados no cookie de sessão: até 32 grupos por sessão, com 64 caracteres cada. Exceder qualquer um dos limites não reduz a lista; o Jamdesk rejeita o token inteiro com um 401 e não concede nenhuma sessão.

Preenchimento prévio do playground de API

Se sua documentação tiver um playground de API, você poderá preenchê-lo previamente para visitantes autenticados, para que não precisem colar sua própria chave de API. Inclua apiPlaygroundInputs no payload do JWT:

{
  "host": "acme.jamdesk.app",
  "apiPlaygroundInputs": {
    "header": { "Authorization": "Bearer sk_live_user_specific_token" },
    "query": { "org_id": "acme-corp" },
    "path": { "workspace_id": "ws_123" }
  }
}

• header.Authorization preenche previamente o campo de autenticação do playground. Um prefixo Bearer é removido automaticamente, se presente.
• query e path preenchem previamente quaisquer nomes de parâmetros correspondentes no endpoint atual.
• As seções server e cookie não são compatíveis. Somente header, query e path são aplicadas.
• O preenchimento prévio nunca substitui um valor que o visitante já tenha digitado no playground.

Referência do payload

Logout

Visitantes autenticados têm um link Log out no cabeçalho da documentação. Ele os envia para /_jd/auth/logout, que limpa o cookie de sessão e redireciona para seu loginUrl. Você também pode criar um link direto para esse endereço no seu próprio aplicativo, caso queira disponibilizar em outro local um link para “sair da documentação”. É uma solicitação GET simples, sem necessidade de corpo ou cabeçalhos.

Comportamento dos recursos com autenticação

Solução de problemas

Nota de segurança

apiPlaygroundInputs, incluindo qualquer valor de Authorization inserido nele, pode ser lido pelo JavaScript em execução no seu site de documentação por meio do endpoint de informações da sessão que alimenta o preenchimento prévio do playground. O preenchimento prévio é conveniente, mas não é apropriado para segredos com privilégios elevados.

Envie credenciais por usuário, com o menor privilégio necessário e limitadas ao que aquele visitante tem permissão para fazer; nunca use uma chave administrativa de toda a organização. Considere tudo o que você inserir em apiPlaygroundInputs como visível para a pessoa que navega pela documentação, pois é.

Migrar da proteção por senha

A troca de uma senha compartilhada pela autenticação JWT não exige indisponibilidade, e o site permanece protegido durante todo o processo. Faça isso nesta ordem:

{
  "auth": {
    "password": { "enabled": false },
    "jwt": { "enabled": true, "loginUrl": "https://app.example.com/docs-login" }
  }
}

O que vem a seguir?