Configuração de Personalização
Choosing a handshake
Esta é a documentação para os métodos de Personalização do Handshake. A Autenticação oferece um conjunto diferente de métodos Handshake.
Antes que seus usuários possam acessar conteúdo personalizado, eles devem ser autenticados. Mintlify suporta três métodos de Handshake de Personalização:
- Sessão Compartilhada: Utilize o mesmo token de sessão usado pelo seu painel para autenticar usuários.
- JWT: Use seu próprio fluxo de login para enviar informações do usuário para seus documentos via JWT na URL.
- OAuth 2.0: Integre com seu servidor OAuth para permitir o login do usuário via fluxo PKCE.
Pré-requisitos
- Você tem um painel ou outro portal de usuário hospedado em seu domínio.
- As credenciais de sessão dos seus usuários são armazenadas como cookies.
- Você pode criar um novo endpoint de API na mesma origem ou em um subdomínio do seu painel.
- Se seu painel estiver em
foo.com, a API URL deve começar comfoo.comou*.foo.com - Se seu painel estiver em
dash.foo.com, a API URL deve começar comdash.foo.comou*.dash.foo.com
- Se seu painel estiver em
- Seus documentos estão hospedados no mesmo domínio que seu painel.
- Se seu painel estiver em
foo.com, seus docs deve ser hospedado emfoo.comou*.foo.com - Se o seu painel estiver em
*.foo.com, seus docs devem ser hospedados emfoo.comou*.foo.com
- Se seu painel estiver em
- Você tem um painel ou outro portal de usuário hospedado em seu domínio.
- As credenciais de sessão dos seus usuários são armazenadas como cookies.
- Você pode criar um novo endpoint de API na mesma origem ou em um subdomínio do seu painel.
- Se seu painel estiver em
foo.com, a API URL deve começar comfoo.comou*.foo.com - Se seu painel estiver em
dash.foo.com, a API URL deve começar comdash.foo.comou*.dash.foo.com
- Se seu painel estiver em
- Seus documentos estão hospedados no mesmo domínio que seu painel.
- Se seu painel estiver em
foo.com, seus docs deve ser hospedado emfoo.comou*.foo.com - Se o seu painel estiver em
*.foo.com, seus docs devem ser hospedados emfoo.comou*.foo.com
- Se seu painel estiver em
- Você tem algum fluxo de login existente.
- Você pode adicionar uma etapa final neste fluxo de login que cria um JWT e redireciona para os docs.
- Você tem um servidor OAuth existente que suporta o fluxo PKCE.
- Você pode criar um novo endpoint de API que pode ser acessado pelo token de acesso OAuth retornado.
Prós e Contras
Pros:
- Usuários que estão logados no seu painel são automaticamente logados nos seus docs
- As sessões dos seus usuários são persistentes, o que significa que você pode atualizar dados sem exigir login adicional
- Configuração mínima necessária
Cons:
- Seus docs farão uma solicitação ao seu backend, o que pode ser indesejável
- Você deve ter um painel que usa autenticação de sessão
- Configuração CORS geralmente é necessária
Pros:
- Usuários que estão logados no seu painel são automaticamente logados nos seus docs
- As sessões dos seus usuários são persistentes, o que significa que você pode atualizar dados sem exigir login adicional
- Configuração mínima necessária
Cons:
- Seus docs farão uma solicitação ao seu backend, o que pode ser indesejável
- Você deve ter um painel que usa autenticação de sessão
- Configuração CORS geralmente é necessária
Pros:
- Risco reduzido de abuso do endpoint da API
- Configuração CORS zero
- Sem restrições nas URLs da API
Cons:
- Deve ser capaz de se conectar ao seu fluxo de login existente
- As sessões do painel e a autenticação dos docs são completamente desacopladas, então os usuários precisarão fazer login no seu painel e nos seus docs separadamente
- Toda vez que você quiser atualizar os dados do usuário, seus usuários devem fazer login novamente nos seus docs
- Se os dados dos seus usuários mudam frequentemente, você deve exigir que seus usuários façam login frequentemente ou arriscar ter dados desatualizados nos docs
- Se os dados dos seus usuários raramente mudam, isso não deve ser um problema
Pros:
- Padrão de segurança elevado
- Sem restrições nas URLs da API
Cons:
- Requer trabalho significativo se estiver configurando o servidor OAuth pela primeira vez
- As sessões do painel e a autenticação dos docs são completamente desacopladas, então os usuários precisarão fazer login no seu painel e nos seus docs separadamente
- Pode ser excessivo para algumas aplicações