API
API e contas de integração
Tudo o que você vê e faz no Hive está disponível na API REST (OpenAPI 3.1, /api/v1 ). Outras plataformas usam uma conta de integração com um token enviado como Authorization: Bearer <token> . As contas ficam em Integrações › Central de integrações › API e contas de integração (pede permissão para administrar a API); a documentação de todas as rotas está em Documentação da API (Swagger).
O que você pode fazer aqui
- Criar uma conta de integração por plataforma, escolhendo os domínios de dados, o modo, a validade do token, IPs permitidos, mTLS e um limite de chamadas.
- Trocar (rotacionar) ou revogar um token.
- Ligar o Webhook de CI de uma conta, pausá-lo, trocar o segredo e reenviar entregas.
- Navegar e experimentar todas as rotas na Documentação da API e baixar o openapi.json .
Criar uma conta de integração
Clique em Nova conta de integração.
Dê à conta um nome com letras minúsculas, números e hífens, como cmdb-servicenow , e diga para que serve. O nome aparece na trilha de auditoria de cada chamada.
Escolha os Domínios de dados que a conta pode usar: Ativos e detalhes, Software e uso, Relacionamentos e mapas, Rede, Nuvem/virtualização/Kubernetes, Contratos e licenças, Vulnerabilidades e insights, Alertas e eventos, Chamados e mudanças, Relatórios, Trilha de auditoria, Pessoas e identidade, Sinal de confiança do dispositivo, Telemetria (OpenTelemetry) e Plano de controle do provedor. Escolha o Modo: Somente leitura (recomendado) ou Leitura e envio (necessário para importar ativos, mudar alertas ou enviar chamados e mudanças). Se quiser, escolha o Modelo de CMDB das respostas (modelo do Hive, ServiceNow CSDM ou DMTF CIM) e um Webhook para avisos de mudança (https).
Escolha a Validade do token (90, 180 ou 365 dias) e, se quiser, os IPs permitidos (faixas como 198.51.100.0/24), Exigir certificado do cliente (mTLS) e o Limite de chamadas por minuto (padrão 600; acima dele a API responde 429 com Retry-After).
Clique em Criar conta e gerar token. Copie o token agora: ele aparece uma única vez, e o Hive guarda só uma impressão digital dele. Testar o token agora confere; Exemplo de chamada mostra uma requisição pronta.
A lista de contas
Colunas: Conta de integração, Pode acessar, Modo, Token (vencimento; aviso 15 dias antes),Último uso e Webhook de CI (ligado, configurar ou pausado).
- Trocar token cria um token novo (válido por 365 dias); o antigo continua funcionando por 7 dias para a outra plataforma se atualizar e depois vence sozinho. Nesse período a linha mostra "Dois tokens valendo durante a troca (7 dias)."
- Revogar para todas as chamadas na hora e não pode ser desfeito; para conectar de novo, crie uma conta nova.
- Webhook de CI: Endereço que recebe, Ligar webhook, Pausar/Retomar, Trocar segredo, Enviar teste e as entregas com Enviar de novo. Valide X-Hive-Signature : HMAC-SHA256 de "timestamp.corpo" com o segredo mostrado uma vez.
A mesma aba tem Popular a CMDB da sua plataforma, as Rotas de entrada (POST) e o Proxy de leitura (opcional), um pequeno programa na DMZ que serve só rotas GET.
Documentação da API
Documentação da API (Swagger) abre a documentação de todas as rotas, agrupadas por área, com parâmetros, corpos e respostas (pede permissão de leitura de integrações ou de administração da API).
- Use a caixa de filtro para achar uma área (tag).
- Try it out chama a API com a sua sessão, com as suas permissões. Por padrão só dá para experimentar GET; marque Permitir experimentar POST, PUT, PATCH e DELETE e confirme para rodar requisições de escrita de verdade (elas vão para a auditoria).
- Baixar openapi.json salva o contrato para importar no Postman ou no Bruno.
Exemplo prático: conta somente leitura para o CMDB do ServiceNow
- API e contas de integração › Nova conta de integração. Nome da contacmdb-servicenow , Para que serve "Sincronização noturna do CMDB".
- Domínios de dados Ativos e detalhes, Software e uso, Relacionamentos e mapas; Modo somente leitura; Modelo de CMDB das respostas ServiceNow CSDM.
- Validade do token 365 dias, IPs permitidos198.51.100.0/24 (a faixa do MID server do ServiceNow), limite 600.
- Criar conta e gerar token, Copiar token, Testar o token agora: "O token funciona: o Hive reconheceu a conta de integração." Clique em Copiei o token — fechar.
- O ServiceNow chama GET /api/v1/cis?changed_since=0&limit=500 com Authorization: Bearer hive_tk_… . Uma chamada de outro IP é recusada.
- Onze meses depois a linha mostra o aviso de vencimento. Clique em Trocar token e passe o token novo ao administrador do ServiceNow; o antigo para sozinho 7 dias depois.
Exemplo prático: achar e experimentar uma rota na documentação
- Documentação da API (Swagger), filtre alerts .
- Abra GET /api/v1/alerts , Try it out, digite asset=<id> e Execute: a resposta mostra os alertas abertos daquela máquina, com a duração da requisição.
- Para testar POST /api/v1/assets/lookup , marque Permitir experimentar POST, PUT, PATCH e DELETE, confirme com Permitir e execute; a chamada fica na auditoria com o seu nome. 4. Clique em Baixar openapi.json e importe no Bruno para a equipe de integração.
Cuidados e limites
- O limite vale por conta e por nó do núcleo; as respostas trazem RateLimit-Limit , RateLimit-Remaining e RateLimit-Reset .
- Uma conta revogada não pode ser restaurada.
- Criar, trocar e revogar pedem permissão para administrar a API.
- Pelo proxy de leitura só funcionam contas somente leitura.
- O endereço do webhook precisa ser https público; endereços privados são recusados.
- Não há OAuth para contas de integração.
Relacionados
- Popule seu CMDB em 3 passos
- Integrar com o GRCS
- Grafana e Power BI
- Chamados de ITSM, CMDB e mudanças aprovadas
Popule seu CMDB em 3 passos
Qualquer plataforma pode manter seu CMDB igual ao Hive sem conector dedicado: uma carga inicial, depois só o que mudou, depois avisos de mudança. Tudo usa uma conta de integração criada em Integrações › Central de integrações › API e contas de integração, com o escopo Ativos e detalhes (e Software e uso para incluir o software instalado).
O que você pode fazer aqui
- Exportar todos os itens de configuração (ICs) de uma vez, no modelo do Hive, ServiceNow CSDM ou DMTF CIM.
- Ler só o que mudou desde a última leitura, incluindo os itens removidos.
- Receber um POST assinado para cada IC criado, alterado ou removido.
- Carga inicial
- GET /api/v1/cis/export?model=hive|csdm|cim&include=software devolve todos os ICs ativos em NDJSON (um IC por linha), no arquivo hive-cis.ndjson .
- Ou leia em páginas: GET /api/v1/cis?limit=500 e depois GET /api/v1/cis?cursor=<nextCursor> até hasMore ser false. limit vai até 2000.
- Cada item tem id , class , removed , updatedAt , attributes e, quando pedido, relationships . O modelo vem da conta (Modelo de CMDB das respostas) ou de model= .
- Só o que mudou
- A última página de uma leitura traz o syncToken . Guarde.
- Na próxima vez chame GET /api/v1/cis?changed_since=<syncToken> : vêm só os ICs novos e alterados, e os aposentados com removed: true . Pagine com cursor como antes e guarde o novo syncToken . changed_since=0 (ou sem o parâmetro) é uma leitura completa.
- Avisos de mudança
Em vez de consultar, ligue o Webhook de CI da conta (coluna Webhook de CI › Configurar, ou Webhook para avisos de mudança no assistente). O Hive faz POST de ci.created , ci.updated e ci.removed com o corpo {type, occurredAt, ci} e os cabeçalhos X-Hive-Event , X-Hive-Delivery , X-Hive-Timestamp e X-Hive-Signature: sha256=<HMAC-SHA256 de "timestamp.corpo"> . Falhas são tentadas de novo de 30 s até 12 h. As mudanças também podem ir para um barramento de eventos (Kafka, RabbitMQ, Service Bus, SNS, Pub/Sub).
Ferramentas
Baixe o contrato com Baixar openapi.json (ou abra Documentação da API (Swagger)) e importe no Postman ou no Bruno para ter a coleção completa. Toda chamada usa Authorization: Bearer <token> .
Exemplo prático: carga no ServiceNow CSDM e delta toda noite
- Crie a conta de integração cmdb-servicenow : Domínios de dados Ativos e detalhes e Software e uso, Modo Somente leitura, Modelo de CMDB das respostas ServiceNow CSDM. Copie o token.
- Carga inicial: `` curl -H "Authorization: Bearer hive_tk_…" "https://hive.centralit.com.br/api/v1/cis/export?include=software" -o hive-cis.ndjson ` Chegam 4.180 linhas, com classes como cmdb_ci_server , cmdb_ci_vm_instance , cmdb_ci_computer e cmdb_ci_netgear , e relações "Installed on::Installs" com cmdb_ci_spkg`.
- Leia uma vez com GET /api/v1/cis?limit=2000 até hasMore ser false e guarde o syncToken da última página.
- Na noite seguinte: GET /api/v1/cis?changed_since=<syncToken>&limit=2000 devolve 23 itens: 20 alterados, 2 novos e o NB-OLD-17 com removed: true (foi aposentado). A rotina o marca como aposentado no CMDB e guarda o novo token.
- Depois, a equipe liga o webhook de CI para https://centralit.service-now.com/api/x_hive/ci : cada mudança chega em segundos, assinada; o receptor confere X-Hive-Signature com o segredo mostrado uma vez.
Cuidados e limites
- Um sync token inválido devolve 422 ( invalid-sync-token ); recomece com uma leitura completa.
- A exportação não é retomável; para bases muito grandes, leia em páginas com cursor .
- Os eventos do webhook vão só para contas com o escopo de ativos, a partir do momento em que ele é ligado (sem histórico anterior), e só para os ativos assinados quando a conta tem uma lista.
- O endereço do webhook precisa ser https público.
- O contrato ( /api/openapi.json ) pede login, a não ser que o administrador tenha deixado a documentação da API pública.
Relacionados
- API e contas de integração
- Integrar com o GRCS
- Chamados de ITSM, CMDB e mudanças aprovadas
Integrar com o GRCS
O GRCS traz do Hive só os ativos que têm um risco ativo ou uma não conformidade aberta: o cadastro do ativo, as vulnerabilidades abertas, os alertas abertos, os serviços de negócio e a avaliação dos controles com evidência. Ele usa uma conta de integração e a API REST; o cartão GRCS em Integrações › Central de integrações › Catálogo (categoria GRC e risco) abre o assistente da conta com os escopos certos.
O que você pode fazer aqui
- Criar a conta de integração do GRCS com webhook e limite de chamadas.
- Vincular cada alvo do GRCS a um ativo do Hive pelos identificadores.
- Assinar a conta nos ativos que importam, por id ou tag.
- Ler ativos, achados, alertas, serviços de negócio e conformidade em lotes, e receber eventos.
- Conta de integração
Em Central de integrações › API e contas de integração, clique em Nova conta de integração (ou Conectar no cartão do GRCS). Escolha os Domínios de dados Ativos e detalhes, Vulnerabilidades e insights, Alertas e eventos e Relatórios; Modo Somente leitura (escolha Leitura e envio só se o GRCS gravar a referência dele de volta). Preencha Webhook para avisos de mudança (opcional) e o Limite de chamadas por minuto. O token aparece uma vez.
- Vincular cada alvo do GRCS ao ativo
- POST /api/v1/assets/lookup com até 500 identificadores ( id , externalRef , hwUuid , serial , fqdn , hostname , ip , ou sem tipo para tentar nesta ordem). Cada resposta diz found , none ou ambiguous (com candidatos) e qual identificador casou. O IP é o último recurso: um casamento ambíguo nunca vincula.
- Opcional: grave a referência do GRCS com PUT /api/v1/assets/import (fonte grcs , externalId = id do alvo; precisa de Leitura e envio). Depois, GET /api/v1/assets?externalRef=grcs:<id> o encontra.
- Assinar os ativos que importam
PUT , PATCH ou DELETE /api/v1/api-accounts//assets com ids de ativos ou tags (por exemplo a tag grcs ). A própria conta pode manter sua lista com o próprio token. Com uma lista, o webhook e os eventos cobrem só os ativos assinados; sem lista, tudo o que os escopos permitem. Até 5.000 ativos e 100 tags por chamada, 50.000 entradas por conta.
- Ler em lotes
- GET /api/v1/assets//full — o ativo com hardware, software, serviços, bancos de dados e relacionamentos.
- GET /api/v1/vulnerabilities/findings?asset=a,b,c e GET /api/v1/alerts?asset=a,b,c — até 200 ativos por chamada; com changedSince (24h, 7d ou uma data ISO) a lista vem em ordem de mudança e a próxima página está no cabeçalho Hive-Next-Cursor .
- GET /api/v1/business-services?asset=a,b — os serviços de que cada ativo faz parte, o papel (componente ou dependência) e se é ponto único de falha.
- GET /api/v1/assets//compliance ou POST /api/v1/compliance/assets (até 200 ativos) — cada controle da ISO 27001, PCI DSS, LGPD/GDPR, HIPAA e CIS v8 que se aplica ao ativo: atendido , parcial , nao_atendido ou na , percentual e a evidência medida com a data.
- Eventos
O webhook recebe vulnerability.opened , vulnerability.closed , vulnerability.risk_changed (mudou a severidade, o KEV ou a faixa do EPSS) e compliance.changed , com subject = id do ativo e a assinatura HMAC em X-Hive-Signature , além dos eventos ci.* . Os mesmos eventos podem ir para um barramento de eventos filtrado por uma tag de ativo.
Exemplo prático: o GRCS acompanha 40 servidores críticos
- Catálogo › GRCS › Conectar: o assistente abre com os escopos escolhidos. Nome grcs , webhook https://grcs.centralit.com.br/hooks/hive , limite de 600 por minuto. Copie o token e o segredo do webhook.
- O GRCS envia seus 40 alvos: POST /api/v1/assets/lookup com {"identifiers":[{"value":"SRV-ERP-01"},{"type":"serial","value":"CZ1234ABC"},…]} . 38 voltam found , 1 none e 1 ambiguous com dois candidatos (o analista escolhe o id certo).
- Marque os 39 ativos com a tag grcs no Hive e assine: PUT /api/v1/api-accounts/<id da conta>/assets com {"tags":["grcs"]} .
- Toda noite: GET /api/v1/vulnerabilities/findings?asset=<39 ids>&changedSince=24h , seguindo o Hive- Next-Cursor até ele sumir; depois POST /api/v1/compliance/assets com {"assets": […],"framework":"iso27001"} .
- Durante o dia, uma vulnerabilidade KEV nova no SRV-ERP-01 manda vulnerability.opened ao webhook; o GRCS abre o risco com a evidência.
Cuidados e limites
Acima do limite da conta a API responde 429 com Retry-After ; toda resposta traz RateLimit-Limit , RateLimit-Remaining e RateLimit-Reset . O limite vale por nó do núcleo. Aqui o parâmetro é changedSince ; a rota de ICs usa changed_since .
Relacionados
- API e contas de integração
- Popule seu CMDB em 3 passos
- Conformidade e hardening
- Vulnerabilidades
Grafana e Power BI
O Hive serve conjuntos de dados prontos para ferramentas de BI em /api/v1/bi , só leitura: JSON simples para o Grafana e um feed OData v4 para o Power BI. Os dois usam o token de uma conta de integração ( Authorization: Bearer <token> ), e cada conjunto confere a permissão de leitura do seu domínio, então uma conta vê só o que os escopos dela permitem. Os cartões Grafana e Power BI em Integrações › Central de integrações › Catálogo (categoria BI) criam essa conta para você.
O que você pode fazer aqui
Criar com um clique, pelo catálogo, uma conta somente leitura para o Grafana ou o Power BI.
Listar os conjuntos disponíveis para a conta e lê-los em JSON ou OData.
Montar painéis do Grafana com séries no tempo ( from / to do painel) e relatórios do Power BI que se atualizam pelo feed.
Conjuntos de dados
Conjunto (JSON) | Entity set OData | O que tem | Pede o escopo |
|---|---|---|---|
assets | Assets | id, name, hostname, type, osFamily, os, osVersion, vendor, model, serial, site, user, status, firstSeen, lastSeen | Ativos |
assets-by-type | AssetsByType | type, assets (ativos) | Ativos |
alerts-by-severity | AlertsBySeverity | severity, alerts (abertos), sempre 4 linhas | Alertas |
alerts-open-over- time | OpenAlertsOverTime | time, critical, major, warning, info, total | Alertas |
vulnerabilities-by- severity | VulnerabilitiesBySeverity | severity, findings, cves, assets | Vulnerabilidades |
patch-compliance | PatchCompliance | status (compliant, missing-security, missing-other, not-scanned), assets, percent | Ativos |
license-usage | LicenseUsage | product, edition, metric, acquired, consumed, inUse, balance, status | Ativos ou Contratos |
Todo conjunto respeita o escopo de ativos do perfil (sites, tags, grupos) de quem chama.
JSON para o Grafana
- GET /api/v1/bi lista os conjuntos com título, colunas, a permissão, se está disponível para quem chama e os caminhos.
- GET /api/v1/bi/<conjunto> devolve uma lista JSON de linhas.
- from e to : milissegundos do Grafana ( $ , $ ) ou ISO 8601; padrão os últimos 7 dias.
- interval : 5m, 15m, 1h, 6h ou 1d; sem ele, até 2 dias → 15m, até 31 dias → 1h, mais → 1d (no máximo 5000 pontos).
- limit (padrão 1000, até 10000) e offset ; a próxima página está no cabeçalho Link: <…>; rel="next" .
OData para o Power BI
- Documento de serviço: GET /api/v1/bi/odata ; metadados: GET /api/v1/bi/odata/$metadata ; dados: GET /api/v1/bi/odata/<EntitySet> .
- Opções de consulta: $select , $top , $skip , $count e $format . O servidor pagina de 1000 linhas por vez com @odata.nextLink . $filter e $orderby são recusados ("Filtre e ordene no Power Query depois de carregar os dados").
- Conjuntos que a conta não pode ler ficam fora do documento de serviço e do $metadata .
Exemplo prático: painel do Grafana com ativos por site
- Catálogo › BI › Grafana › Conectar. O assistente Nova conta de integração abre com grafana , somente leitura e os escopos Alertas, Ativos e Vulnerabilidades. Crie e copie o token.
- No Grafana, instale o plugin de fonte de dados Infinity e adicione uma fonte: URL https://hive.centralit.com.br , cabeçalho Authorization = Bearer hive_tk_… (como cabeçalho seguro).
- Painel novo, consulta do tipo JSON, URL /api/v1/bi/assets?limit=10000 . Aparecem as colunas: name, type, site, status…
- Adicione a transformação Group by: agrupe por site e calcule id → Count. Escolha um gráfico de barras: São Paulo 1.240, Rio de Janeiro 610, Recife 180.
- Segundo painel: URL /api/v1/bi/alerts-open-over-time?from=$&to=$ , uma série no tempo com critical, major, warning e info. Mudar o período do painel para 30 dias passa os pontos para 1 hora.
Exemplo prático: feed OData do Power BI com uma conta de API
- Catálogo › BI › Power BI › Conectar, crie a conta powerbi e copie o token. Se o financeiro também precisa de licenças, elas já vêm pelo escopo de Ativos.
- No Power BI Desktop: Obter dados › Consulta nula e, no editor avançado: `` = OData.Feed("https://hive.centralit.com.br/api/v1/bi/odata", [Authorization="Bearer hive_tk_…"], [Implementation="2.0"]) ``
- O navegador lista Assets, AssetsByType, AlertsBySeverity, OpenAlertsOverTime, VulnerabilitiesBySeverity, PatchCompliance e LicenseUsage. Carregue LicenseUsage e PatchCompliance.
- Filtre no Power Query (por exemplo status <> "compliant" ); um $filter no endereço seria recusado.
- Monte o relatório "Licenças: adquiridas × em uso" com product , acquired e inUse . Cada atualização lê o feed de novo, página por página.
Cuidados e limites
- Só o token Bearer é aceito: sem usuário e senha (Basic) e sem token no endereço.
- Um conjunto sem a permissão responde 403 ("This account cannot read this dataset."); sem token, 401.
- O limite de chamadas da conta vale (padrão 600 por minuto); painéis grandes do Grafana contam cada painel.
- As rotas de BI também podem ser servidas pelo proxy de leitura na DMZ, com uma conta somente leitura.
- As telas do Power BI e do Grafana não fazem parte do Hive; os nomes dos menus delas podem mudar entre versões.
Relacionados
- API e contas de integração
- Relatórios e painéis
- Central de integrações