Usuário automático

A API de usuários cadastra, atualiza e remove os usuários de um tenant, com os grupos e as Mesas de cada um. Com ela, o cadastro acompanha o seu sistema sem passar pelo HEC, e o usuário pode ser criado logo antes do login transparente.

Todas as chamadas desta página usam o Tenant Token.

Conferir se o e-mail existe

curl "https://api.horusbi.com.br/v1/tenant/users?email=ana.souza%40cliente.com.br" \
  -H "Authorization: Bearer $TENANT_TOKEN"

{
  "status": "success",
  "data": [
    {
      "id": 812,
      "login": "ana.souza@cliente.com.br",
      "nome": "Ana Souza",
      "ultimo_login": "2026-10-20T13:02:11.000Z",
      "groups": [3],
      "bi_desks": [7],
      "apps_deny": [],
      "table_restrictions": []
    }
  ]
}

data vazio quer dizer que o e-mail não está vinculado a este tenant. O filtro aceita email, login (o mesmo campo) ou id. Sem filtro, a chamada devolve todos os usuários ativos do tenant.

Criar o usuário

curl -X POST https://api.horusbi.com.br/v1/tenant/users \
  -H "Authorization: Bearer $TENANT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "login": "ana.souza@cliente.com.br",
    "nome": "Ana Souza",
    "groups": [3]
  }'

{ "success": true }

Usuários são da plataforma, e o tenant só guarda um vínculo com cada um. Se o e-mail já existe em outro tenant, de qualquer Cliente, a API vincula esse mesmo usuário. Por isso password só vale para usuário criado agora (quem já existia continua com a senha dele), e nome muda o nome do usuário em todos os tenants dele.

Sem password, o usuário fica sem senha e entra só pelo login transparente. Use assim quando o seu sistema for a única porta de entrada.

Dar acesso aos Dashboards

Usuário sem grupo e sem Mesa entra no DataViz e não vê nada. Os quatro campos de permissão valem na criação e na edição:

Campo	Recebe	Efeito
groups	IDs de GET /v1/tenant/groups	O usuário herda as Mesas e as restrições do grupo
bi_desks	IDs de Mesa, de GET /v1/tenant	Libera a Mesa para o usuário direto, sem grupo
apps_deny	IDs de Aplicação	Esconde Aplicações específicas, mesmo dentro de uma Mesa liberada
table_restrictions	{ "tableId": 10, "filters": "..." }	Filtra as linhas que o usuário vê numa tabela

Prefira grupos. Com um grupo por perfil do seu sistema (Diretoria, Gerente, Vendedor), mudar o que um perfil vê é uma edição no HEC, sem reenviar a lista de Mesas de cada usuário.

A API não dá o grupo de administrador: a chamada que tentar volta com O grupo de administrador não pode ser atribuído pela API. Quem vai administrar o tenant recebe esse grupo no HEC.

Manter as permissões em sincronia

Cada lista enviada substitui a anterior inteira. Mandar "groups": [3] para quem está nos grupos 3 e 5 tira o usuário do grupo 5. Campo que não vai no corpo fica como está.

Com isso dá para sincronizar a cada login: antes de gerar a URL, envie a lista completa de grupos que o perfil do usuário pede hoje.

curl -X PUT https://api.horusbi.com.br/v1/tenant/users \
  -H "Authorization: Bearer $TENANT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"login": "ana.souza@cliente.com.br", "groups": [3, 4]}'

Duas exceções evitam que o tenant fique sem dono: o grupo de administrador não sai por omissão da lista, e os grupos que o fornecedor da plataforma administra também não.

Remover quem saiu

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

O vínculo com o tenant acaba, e a sessão aberta cai na próxima página que o usuário abrir. Nos outros tenants dele, nada muda. Se o seu cliente HTTP não manda corpo em DELETE, use POST /v1/tenant/users/delete com o mesmo corpo.

Erros

Resposta	Causa
"success": false, Login já está cadastrado	O e-mail já está vinculado a este tenant. Use PUT para mudar permissões
"success": false, Grupo 99 não encontrado	ID de grupo que não é deste tenant. Vale o mesmo para Mesa, Aplicação e tabela
"success": false, Este usuário é administrado pelo fornecedor da plataforma...	Usuário da equipe do Cliente, que a API não altera
HTTP 500, error com Limite de N usuário(s) atingido...	O tenant chegou à franquia de usuários contratada

Operação de usuário que falha responde HTTP 200, com "success": false e o motivo em message. A franquia é a exceção: volta como HTTP 500, com o motivo no campo error.

Para criar também o tenant a partir do seu sistema, siga para o Tenant automático.