Login transparente

O seu backend manda o e-mail de um usuário do tenant para a API e recebe uma URL de login. Aberta no navegador, essa URL entra no DataViz sem pedir senha. Para isso, o tenant, os Dashboards e os usuários podem estar cadastrados no HEC.

Você precisa do Tenant Token do tenant (HEC, cadastro do tenant, aba Desenvolvedor) e de um usuário vinculado a esse tenant.

Gerar a URL

curl -X POST https://api.horusbi.com.br/v1/tenant/login \
  -H "Authorization: Bearer $TENANT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"login": "ana.souza@cliente.com.br"}'

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "url": "https://bi.suaempresa.com.br/auth/api/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...?showMenu=0"
}

Esta resposta vem sem o envelope status/data dos outros endpoints. O endereço da url sai do campo domínio do tenant. Tenant criado sem domínio fica em dataviz.horusbi.com.br, e a URL sai com o endereço da Horus em vez do seu.

WARNING

Se o domínio do tenant tem mais de um endereço separado por vírgula, a url sai com a lista inteira no lugar do host e não abre. Nesse caso monte a URL você mesmo a partir do token: https://<seu-dominio>/auth/api/<token>?showMenu=0.

Abrir o DataViz

A mesma URL serve para três jeitos de abrir.

<iframe src="https://bi.suaempresa.com.br/auth/api/eyJhbGciOi...?showMenu=0"
        style="width: 100%; height: 100vh; border: 0"></iframe>

Para abrir numa aba ou na janela atual, redirecione para a url. Em aplicativo desktop ou mobile, carregue a url numa WebView.

O endereço /auth/api/<token> grava a sessão num cookie e leva o usuário para a página inicial, ou para a página de ref. Dali em diante é como um login com senha: o usuário vê o que as permissões dele no tenant deixam.

Parâmetros da URL

Os parâmetros vão na querystring da url. O DataViz guarda todos num cookie junto com o login, então eles valem para a sessão inteira.

Parâmetro	Valores	Padrão	Efeito
showMenu	0, 1	1	0 esconde o menu lateral do DataViz. A url da API já vem com showMenu=0
showDesksIcon	0, 1	1	0 esconde o ícone de Mesas no menu
forceTheme	light, dark	tema do usuário	Força o tema claro ou escuro, para casar com o do seu sistema
ref	rota em Base64	/	Página que abre depois do login

Para mostrar o menu do DataViz, troque showMenu=0 por showMenu=1 na url.

Abrir direto num Dashboard

Com o menu escondido, quem leva o usuário de um Dashboard a outro é o seu sistema. Codifique a rota em Base64 e passe em ref:

Abre	Rota	ref
Dashboard da Aplicação 42	/app/42	L2FwcC80Mg==
Mesa 7	/desks/7	L2Rlc2tzLzc=

const ref = Buffer.from("/app/42").toString("base64");
const destino = `${url}&ref=${encodeURIComponent(ref)}`;

Os IDs das Aplicações e das Mesas vêm em GET /v1/tenant (campos bi_apps e bi_desks). O que cada usuário pode abrir vem em GET /v1/tenant/users (campos bi_desks e apps_deny). Com os dois, o seu sistema monta um menu só com o que o usuário enxerga.

Use só caracteres ASCII na rota: acento ou emoji no caminho chega quebrado.

Quanto tempo a sessão dura

O token vale 1 hora a partir de quando foi gerado, e a sessão acaba junto com ele. Navegar pelo DataViz não estica o prazo. Depois de 1 hora, a próxima página que o usuário abrir no iframe mostra a tela de login do DataViz.

Gere uma URL nova cada vez que o usuário abrir o BI no seu sistema, e não guarde URL para reaproveitar. Se o usuário costuma deixar o BI aberto por horas, recarregue o iframe com uma URL nova antes de completar 1 hora.

Trate a URL como uma senha temporária: não registre em log e não mande por e-mail. O token não é de uso único, e quem tiver a URL entra como aquele usuário enquanto ela valer.

Erros

Resposta	Causa
HTTP 401, corpo Unauthorized	Tenant Token ausente, inválido ou regenerado, ou o tenant está inativo
HTTP 200, "success": false, Usuário não encontrado	O e-mail não existe ou não está vinculado a este tenant
HTTP 200, "success": false, Este usuário não pode entrar pela API do tenant.	O e-mail é de alguém da equipe Horus, que não entra por login transparente

Usuário inexistente volta com HTTP 200. Confira o campo success antes de usar a url.

Para cadastrar o usuário que falta sem passar pelo HEC, veja Usuário automático.