Login transparente

Tipo

Como fazer

Para

Parceiro whitelabel, Desenvolvedor

Na tela

HEC › Tenants › Desenvolvedor

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.

Você precisa do Tenant Token (cadastro do tenant no HEC, aba Desenvolvedor) e de um usuário vinculado a esse tenant. O tenant, os Dashboards e os usuários podem ter sido cadastrados no HEC ou pela API.

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@lojaexemplo.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 das outras rotas. 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 HorusBI no lugar 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 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. No iframe:

<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 vale o mesmo que 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, e 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 de dois lugares: em GET /v1/tenant/users, bi_desks e apps_deny trazem só o que foi liberado ou negado direto para o usuário, e groups traz os grupos dele; o que cada grupo libera e nega vem em GET /v1/tenant/groups, nos mesmos campos. Somando os dois, o seu sistema monta um menu só com o que o usuário enxerga. Administradores do tenant veem tudo.

Use só caracteres ASCII na rota: acento ou emoji no caminho chega quebrado. Do ref vale só o caminho: se ele trouxer outro domínio, o usuário fica no DataViz que recebeu o login.

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. Passada 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 DataViz no seu sistema, e não guarde URL para reaproveitar. Se o usuário costuma deixar o DataViz 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 pode ser usado mais de uma vez, e quem tiver a URL entra como aquele usuário enquanto ela valer.

Se der errado

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

Até a versão de 28/10/2026 da API, os erros 404 e 403 voltavam com HTTP 200. O corpo é o mesmo de antes, então quem confere o campo success continua funcionando. Quem trata qualquer status fora de 2xx como falha de rede passa a receber esses erros por esse caminho.

Relacionado

• Usuário automático, para cadastrar o usuário que falta sem passar pelo HEC
• Códigos de erro da API
• Solução de problemas