Como configurar acesso restrito e autenticação de usuários no Mintlify para documentação de API privada

Times de engenharia e arquitetos de plataformas de desenvolvimento que gerenciam documentações de APIs privadas para clientes corporativos, parceiros comerciais ou integrações confidenciais enfrentam um dilema clássico: oferecer uma experiência moderna e rica em recursos com Playgrounds de teste interativos, ao mesmo tempo em que isolam estritamente endpoints sensíveis, rotas de liquidação financeira e SDKs proprietários contra scrapers públicos e acessos não autorizados.

O Mintlify resolve essa equação combinando seu motor baseado em MDX e OpenAPI com quatro mecanismos de controle de acesso: proteção interna para membros da organização, restrição global por senha, logon único corporativo (SSO / OAuth 2.0) e autenticação com JSON Web Tokens (JWT) assinados. Este guia detalha os requisitos arquiteturais, fluxos de configuração, regras de controle de acesso baseado em grupos (RBAC) e a injeção segura de credenciais no API Playground para ambientes de produção.

Pré-requisitos de arquitetura e restrições de domínio

Antes de implementar qualquer método de autenticação, a equipe técnica deve atentar para as regras fundamentais de hospedagem do Mintlify:

1. Requisito de domínio dedicado: Tanto a autenticação total quanto a parcial exigem que a documentação seja hospedada em um domínio personalizado exclusivo (como docs.api.example.com) ou em um subdomínio do Mintlify (example.mintlify.site). O acesso restrito com autenticação não é suportado em subcaminhos (como example.com/docs). Para subcaminhos, é possível utilizar apenas recursos de personalização sem bloqueio rígido de visualização.
2. Escopo do acesso (Total vs. Parcial): É possível configurar a Autenticação Total (Full) (bloqueando todo o portal e os esquemas OpenAPI por trás de login obrigatório) ou a Autenticação Parcial (Partial) (mantendo guias introdutórios públicos e restringindo apenas módulos empresariais e rotas internas).
3. Segurança em deploys de pré-visualização (Preview Deployments): Em fluxos de CI/CD orientados por Git, links de pré-visualização de Pull Requests podem expor endpoints recém-criados. Ao ativar a autenticação no painel do Mintlify, todos os deploys de pré-visualização herdam automaticamente as barreiras de proteção.

Matriz comparativa dos métodos de autenticação

Método 1: Proteção por senha (Bloqueio rápido e simples)

A proteção por senha oferece uma camada imediata para projetos em fase inicial com parceiros estratégicos ou demonstrações confidenciais, sem a necessidade de configurar um provedor de identidade.

Fluxo de configuração

1. Acesse o painel de controle no Mintlify Dashboard e selecione a aba Access.
2. Altere o campo Visibility de Public para Private.
3. Defina Method como Password.
4. Digite uma senha compartilhada forte e clique em Save changes.

Limitações técnicas

Embora a configuração seja concluída em menos de dois minutos, todos os usuários compartilham a mesma credencial. Não é possível auditar ações individuais, aplicar permissões por perfil ou revogar o acesso de um único parceiro sem alterar a senha de todos os demais. Esse método deve ser restrito a testes preliminares.

Método 2: SSO corporativo e OAuth 2.0 (Federação de identidade)

Para portais de engenharia internos ou integrações exclusivas com clientes corporativos, federar a identidade via SAML 2.0 ou OAuth 2.0 garante conformidade com políticas de segurança da informação e desativação centralizada de acessos.

Integração com Okta SAML 2.0

1. Obter endpoints do Mintlify: No painel do Mintlify, navegue até Security, clique em Configure e escolha Okta SAML. Copie a Single sign on URL (URL de ACS) e a Audience URI (SP Entity ID).
2. Criar a aplicação no Okta: No console do Okta, vá para Applications > Create App Integration > SAML 2.0. Cole a URL e a URI fornecidas pelo Mintlify.
3. Mapear atributos de usuário: Configure as declarações de atributos exigidas:
   • firstName -> user.firstName
   • lastName -> user.lastName
   • Name -> user.email (com formato Name ID configurado como EmailAddress).
4. Vincular metadados: Copie a Metadata URL gerada no Okta, insira-a no campo correspondente no painel do Mintlify e salve as alterações.

Após a ativação, qualquer visitante no domínio da documentação será redirecionado para o portal de login do IdP corporativo antes de ter acesso às especificações de API.

Método 3: Autenticação personalizada com JWT (Integração contínua com a aplicação)

Em plataformas SaaS comerciais, os clientes já realizam login no painel principal da sua aplicação. Para evitar que os desenvolvedores precisem se autenticar novamente ao abrir a documentação privada, o Mintlify suporta autenticação via JWT assinado com chave assimétrica.

Fluxo da arquitetura

Navegador do usuário          Backend da sua aplicação (App)       Documentação Mintlify
         |                                |                                   |
         | 1. Clica em "Documentação API" |                                   |
         |------------------------------->|                                   |
         |                                | 2. Cria payload com permissões    |
         |                                |    e assina JWT com chave ES256   |
         | 3. Redireciona para os docs    |                                   |
         |    https://docs.example.com/#JWT|                                  |
         |<-------------------------------|                                   |
         |                                                                    |
         | 4. Solicita a página com o JWT no fragmento (Hash) da URL          |
         |------------------------------------------------------------------->|
         |                                | 5. Valida assinatura ES256,       |
         |                                |    aplica grupos e remove o Hash  |
         | 6. Renderiza endpoints restritos e Playground preenchido           |
         |<-------------------------------------------------------------------|

Passo a passo de implementação

1. No painel do Mintlify, acesse as configurações de Access (ou Personalization), selecione JWT e informe a URL de login da sua aplicação.
2. Gere um par de chaves criptográficas no painel e guarde a chave privada em um cofre de segredos seguro (como AWS Secrets Manager ou KMS).
3. No backend do seu serviço, gere o JWT assinado com o algoritmo ES256 contendo os dados do usuário, tempo de vida da sessão e permissões de grupo:

import jwt from "jsonwebtoken";

// Exemplo em Node.js para emissão de token de acesso ao Mintlify
export function generateMintlifyDocToken(user, partnerAccount) {
  const payload = {
    // Declarações padrão JWT
    sub: user.id,
    exp: Math.floor(Date.now() / 1000) + 10, // Expiração curta: 10 segundos ou menos
    
    // Tempo de sessão ativa no portal Mintlify
    expiresAt: Math.floor(Date.now() / 1000) + (60 * 60 * 8), // 8 horas de sessão
    
    // Contexto de usuário para renderização condicional em MDX
    content: {
      userId: user.id,
      email: user.email,
      organization: partnerAccount.name,
      plan: partnerAccount.tier // Ex.: "enterprise" ou "growth"
    },
    
    // Grupos para controle de navegação e bloqueio de páginas
    groups: [partnerAccount.tier, "partner-tier-1"],
    
    // Credenciais para injeção automática no API Playground
    apiPlaygroundInputs: {
      header: {
        Authorization: `Bearer ${partnerAccount.ephemeralSandboxKey}`
      }
    }
  };

  return jwt.sign(payload, process.env.MINTLIFY_PRIVATE_SIGNING_KEY, {
    algorithm: "ES256"
  });
}

4. Ao redirecionar o usuário para a documentação, anexe o JWT como um fragmento de URL (Hash):

   https://docs.api.example.com/api/v2/private-settlement#eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...
   

   O cliente do Mintlify intercepta o token no fragmento, valida a assinatura com a chave pública previamente cadastrada, inicia a sessão local e remove imediatamente o Hash do histórico do navegador, impedindo vazamentos via referrers ou histórico de navegação.

Controle de acesso baseado em funções (RBAC) e bloqueio por página

Após validar a identidade, o time de engenharia pode restringir o conteúdo conforme o nível de contrato de cada parceiro.

1. Bloqueio no Frontmatter de arquivos MDX

Declare os grupos autorizados no cabeçalho YAML dos arquivos .mdx correspondentes:

---
title: "Webhooks de liquidação financeira"
description: "Especificação de notificações de pagamento em alta escala"
groups: ["enterprise", "fintech-partners"]
---

Se a sessão JWT ou SSO do visitante não contiver o grupo especificado, o Mintlify remove o link da barra de navegação lateral e bloqueia o acesso direto retornando status de restrição (404 ou tela de bloqueio).

2. Renderização condicional em MDX com userContext

Para guias gerais que contêm seções específicas para planos empresariais, utilize o objeto userContext:

# Políticas de taxa de transferência

{userContext?.content?.plan === "enterprise" ? (
  <Card title="Cota dedicada para parceiros" icon="shield-check">
    Sua conta tem direito a 10.000 requisições por segundo e suporte com SLA crítico.
  </Card>
) : (
  <Card title="Limite padrão" icon="gauge">
    O limite padrão é de 200 requisições por minuto. Entre em contato para contratar cotas superiores.
  </Card>
)}

3. Segregação de conteúdo para humanos e agentes de IA

O Mintlify compila a documentação em Markdown para ferramentas de inteligência artificial. Para evitar que instruções confidenciais de segurança sejam indexadas por crawlers e LLMs, utilize o componente <Visibility>:

<Visibility for="humans">
  <Note>Chaves de produção devem ser rotacionadas a cada 90 dias pelo portal do cliente.</Note>
</Visibility>

<Visibility for="agents">
  Requisições de API devem incluir um token Bearer no cabeçalho Authorization.
</Visibility>

Proteção no API Playground interativo

O Playground interativo é um recurso de grande destaque, mas requer cautela rigorosa para evitar o vazamento de chaves mestras e requisições destrutivas em produção.

1. Pré-preenchimento seguro via apiPlaygroundInputs

Em vez de solicitar que os desenvolvedores copiem chaves de produção para o navegador, injete credenciais de sandbox temporárias através do payload da sessão:

{
  "apiPlaygroundInputs": {
    "server": {
      "environment": "sandbox"
    },
    "header": {
      "Authorization": "Bearer sbx_partner_9981aef0"
    },
    "query": {
      "version": "2026-10"
    }
  }
}

O Mintlify mapeia esses valores diretamente para os campos de cabeçalho e parâmetros ao carregar a página da API.

2. Boas práticas indispensáveis de segurança

• Forçar servidores de sandbox e mock: Configure as URLs de servidores no docs.json para que o padrão aponte para instâncias de simulação ou sandbox, nunca diretamente para bancos de dados de produção.
• Nunca injetar chaves mestras permanentes: Credenciais enviadas via apiPlaygroundInputs devem ser temporárias e limitadas a operações de teste.
• Usar x-default no OpenAPI para placeholders: Em documentações públicas ou protegidas por senha onde não há JWT dinâmico, defina modelos genéricos em securitySchemes (por exemplo, x-default: "SUA_CHAVE_SANDBOX"), evitando expor chaves reais no repositório.

Lista de verificação para produção

• Topologia de domínio: Documentação configurada em subdomínio dedicado (docs.partner.example.com), evitando subcaminhos sem suporte a autenticação.
• Escopo de bloqueio: Definição clara entre autenticação total (Full) ou parcial (Partial) na aba Access.
• Armazenamento de chaves: Chave privada ES256 protegida em KMS ou cofre de segredos, nunca comitada no Git.
• Tempo de vida de tokens: Valor do claim exp do JWT configurado em 10 segundos ou menos para evitar ataques de repetição.
• Grupos configurados: Páginas confidenciais sinalizadas com a propriedade groups no Frontmatter dos arquivos MDX.
• Isolamento do Playground: Servidores de teste restritos a ambientes de simulação e sandbox.
• Proteção de pré-visualizações: Validação de que deploys gerados por PRs possuem as mesmas restrições de acesso.

Seguindo este modelo, equipes de engenharia oferecem uma experiência interativa de alta qualidade aos seus parceiros estratégicos sem abrir mão de um modelo robusto de segurança para suas APIs privadas.

Referências

• Authentication setup - Mintlify
• SSO - Mintlify
• Personalized content - Mintlify