A personalização adapta sua documentação para cada usuário quando ele está autenticado. Por exemplo, você pode preencher previamente as chaves de API, exibir conteúdo específico do plano ou função, ou ocultar seções às quais ele não precisa ter acesso.

​
Recursos de personalização

Personalize o conteúdo com estas funcionalidades de personalização.

​
Preenchimento automático de chave de API

Preencha automaticamente os campos do Playground de API com valores específicos do usuário, retornando nomes de campos que correspondam aos do playground nos seus dados de usuário. Os nomes de campos nos seus dados de usuário devem corresponder exatamente aos nomes no Playground de API para que o preenchimento automático funcione.

​
Conteúdo dinâmico em MDX

Exiba conteúdo dinâmico com base em informações do usuário, como nome, plano ou organização, usando a variável user. 
Welcome back, {user.firstName}! Your {user.org?.plan} plan includes...
Veja a seção Formato de dados do usuário abaixo para exemplos detalhados e instruções de implementação.

​
Visibilidade da página

Restrinja quais páginas ficam visíveis para seus usuários adicionando o campo groups ao frontmatter das suas páginas. Por padrão, todas as páginas são visíveis para todos os usuários. Os usuários só verão as páginas dos groups aos quais pertencem. 
---
title: "Managing your users"
description: "Adding and removing users from your organization"
groups: ["admin"]
---

​
Formato de dados do usuário

Ao implementar personalização, seu sistema retorna dados do usuário em um formato específico que permite a customização de conteúdo. Esses dados podem ser enviados como um objeto JSON bruto ou dentro de um JWT assinado, dependendo do método de handshake. A estrutura dos dados é a mesma em ambos os casos. 
type User = {
  expiresAt?: number;
  groups?: string[];
  content?: Record<string, any>;
  apiPlaygroundInputs?: {
    header?: Record<string, any>;
    query?: Record<string, any>;
    cookie?: Record<string, any>;
    server?: Record<string, string>;
  };
};
​
expiresAt
number
Tempo de expiração da sessão em segundos desde a época Unix. Se o usuário carregar uma página após esse tempo, seus dados armazenados serão automaticamente excluídos e ele deverá se autenticar novamente.
Para handshakes com JWT: Isso difere da claim exp do JWT, que determina quando um JWT é considerado inválido. Defina a claim exp do JWT para uma duração curta (10 segundos ou menos) por segurança. Use expiresAt para o tempo real da sessão (de horas a semanas).
​
groups
string[]
Lista de grupos aos quais o usuário pertence. Páginas com groups correspondentes em seu frontmatter ficam visíveis para esse usuário.Exemplo: Usuário com groups: ["admin", "engineering"] pode acessar páginas marcadas com os grupos admin ou engineering.
​
content
object
Dados personalizados acessíveis no seu conteúdo MDX via a variável user. Use isso para personalização dinâmica em toda a sua documentação.Exemplo básico:
{ "firstName": "Ronan", "company": "Acme Corp", "plan": "Enterprise" }
Uso em MDX:
Welcome back, {user.firstName}! Your {user.plan} plan includes...
Com os dados de user do exemplo, isso seria renderizado como: Welcome back, Ronan! Your Enterprise plan includes…Renderização condicional avançada:
Authentication is an enterprise feature. {
  user.org === undefined
    ? <>To access this feature, first create an account at the <a href="https://dashboard.mintlify.com/login">Mintlify dashboard</a>.</>
    : user.org.plan !== 'enterprise'
      ? <>You are currently on the ${user.org.plan ?? 'free'} plan. See <a href="https://mintlify.com/pricing">our pricing page</a> for information about upgrading.</>
      : <>To request this feature for your enterprise org, contact your admin.</>
}
As informações em user estão disponíveis apenas para usuários autenticados. Para usuários não autenticados, o valor de user será {}. Para evitar que a página quebre para usuários não autenticados, sempre use optional chaining nos campos de user. Por exemplo, {user.org?.plan}.
​
apiPlaygroundInputs
object
Valores específicos do usuário que pré-preenchem os campos do Playground de API. Economiza tempo ao preencher automaticamente os dados do usuário durante os testes de APIs.Exemplo:
{
  "header": { "X-API-Key": "user_api_key_123" },
  "server": { "subdomain": "foo" },
  "query": { "org_id": "12345" }
}
Se um usuário fizer solicitações em um subdomínio específico, você pode enviar { server: { subdomain: 'foo' } } como um campo apiPlaygroundInputs. Esse valor será pré-preenchido em qualquer página de API que utilize o valor de subdomain.
Os campos header, query e cookie só serão pré-preenchidos se fizerem parte do seu esquema de segurança OpenAPI. Se um campo estiver nas seções Authorization ou Server, ele será pré-preenchido. Criar um parâmetro de header padrão chamado Authorization não habilita esse recurso.

​
Exemplo de dados de usuário

{
  "expiresAt": 1735689600,
  "groups": ["admin", "beta-users"],
  "content": {
    "firstName": "Jane",
    "lastName": "Smith",
    "company": "TechCorp",
    "plan": "Enterprise",
    "region": "us-west"
  },
  "apiPlaygroundInputs": {
    "header": {
      "Authorization": "Bearer abc123",
      "X-Org-ID": "techcorp"
    },
    "server": {
      "environment": "production",
      "region": "us-west"
    }
  }
}

​
Configurando a personalização

Selecione o método de handshake que você deseja configurar.

​
Pré-requisitos

  • Um sistema de login capaz de gerar e assinar JWTs
  • Um serviço de backend capaz de criar URLs de redirecionamento

​
Implementação

1

Gerar uma chave privada.

  1. No seu dashboard, acesse Authentication.
  2. Selecione Personalization.
  3. Selecione JWT.
  4. Insira a URL do seu fluxo de login existente e selecione Save changes.
  5. Selecione Generate new key.
  6. Armazene sua chave com segurança em um local acessível pelo seu backend.
2

Integrar a personalização do Mintlify ao seu fluxo de login.

Modifique seu fluxo de login existente para incluir estas etapas após o login do usuário:
  • Crie um JWT contendo as informações do usuário autenticado no formato User. Consulte a seção User data format acima para mais informações.
  • Assine o JWT com a chave secreta, usando o algoritmo ES256.
  • Crie uma URL de redirecionamento de volta para a sua documentação, incluindo o JWT como hash.

​
Exemplo

Sua documentação está hospedada em docs.foo.com. Você quer que ela seja separada do seu dashboard (ou você não tem um dashboard) e deseja habilitar a personalização.Gere um segredo de JWT. Em seguida, crie um endpoint de login em https://foo.com/docs-login que inicie um fluxo de login para a sua documentação.Após verificar as credenciais do usuário:
  • Gere um JWT com os dados do usuário no formato do Mintlify.
  • Assine o JWT e redirecione para https://docs.foo.com#{SIGNED_JWT}.
import * as jose from 'jose';
import { Request, Response } from 'express';

const TWO_WEEKS_IN_MS = 1000 * 60 * 60 * 24 * 7 * 2;

const signingKey = await jose.importPKCS8(process.env.MINTLIFY_PRIVATE_KEY, 'ES256');

export async function handleRequest(req: Request, res: Response) {
  const user = {
    expiresAt: Math.floor((Date.now() + TWO_WEEKS_IN_MS) / 1000),
    groups: res.locals.user.groups,
    content: {
      firstName: res.locals.user.firstName,
      lastName: res.locals.user.lastName,
    },
  };

  const jwt = await new jose.SignJWT(user)
    .setProtectedHeader({ alg: 'ES256' })
    .setExpirationTime('10 s')
    .sign(signingKey);

  return res.redirect(`https://docs.foo.com#${jwt}`);
}

​
Preservando âncoras de página

Para redirecionar usuários para seções específicas após o login, use este formato de URL: https://docs.foo.com/page#jwt={SIGNED_JWT}&anchor={ANCHOR}.Exemplo:
  • URL original: https://docs.foo.com/quickstart#step-one
  • URL de redirecionamento: https://docs.foo.com/quickstart#jwt={SIGNED_JWT}&anchor=step-one