---
title: API
slug: uvd7-api
createdAt: 2026-10-23T17:04:30.431Z
---
## API e contas de integração
::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/M_4OVM2m8kMRFQxW5UkSL_image.png" size="137" caption="Tela: API e contas de integração (1/2)" isUploading="false" width="1366" height="860" darkWidth="1366" darkHeight="860" showCaption="true"}
::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/w1Wnedfzd0LAsWa0nZDTk_image.png" size="137" caption="Tela: API e contas de integração (2/2)" isUploading="false" width="1366" height="860" darkWidth="1366" darkHeight="860" showCaption="true"}
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 \ . 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**
1. **API e contas de integração › Nova conta de integração**. **Nome da conta**cmdb-servicenow , **Para que serve** "Sincronização noturna do CMDB".
2. **Domínios de dados** Ativos e detalhes, Software e uso, Relacionamentos e mapas; **Modo **somente leitura; **Modelo de CMDB das respostas** ServiceNow CSDM.
3. **Validade do token** 365 dias, **IPs permitidos**198.51.100.0/24 (a faixa do MID server do ServiceNow), limite 600.
4. **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**.
5. O ServiceNow chama GET /api/v1/cis?changed\_since=0\&limit=500 com Authorization: Bearer hive\_tk\_… . Uma chamada de outro IP é recusada.
6. 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**
1. **Documentação da API (Swagger)**, filtre alerts .
2. Abra GET /api/v1/alerts , **Try it out**, digite asset=\ e **Execute**: a resposta mostra os alertas abertos daquela máquina, com a duração da requisição.
3. 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.
1. **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=\ 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= .
2. **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=\ : 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.
3. **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=\ . 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 \ .
***
### Exemplo prático: carga no ServiceNow CSDM e delta toda noite
1. 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.
2. 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\`.
3. Leia uma vez com GET /api/v1/cis?limit=2000 até hasMore ser false e guarde o syncToken da última página.
4. Na noite seguinte: GET /api/v1/cis?changed\_since=\\&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.
5. 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.
1. **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.
2. **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:\ o encontra.
3. **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.
4. **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.
5. **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
1. **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.
2. 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).
3. Marque os 39 ativos com a tag grcs no Hive e assine: PUT /api/v1/api-accounts/\/assets com \{"tags":\["grcs"]} .
4. 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"} .
5. 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
::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/Snjha0WUVnEJGCvW86Mbm_image.png" size="137" caption="Tela: Grafana e Power BI" isUploading="false" width="1366" height="860" darkWidth="1366" darkHeight="860" showCaption="true"}
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 \ ), 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/\ 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/\ .
- 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
1. **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.
2. 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).
3. Painel novo, consulta do tipo JSON, URL /api/v1/bi/assets?limit=10000 . Aparecem as colunas: name, type, site, status…
4. 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.
5. 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
1. **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.
2. 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"]) \`\`
3. O navegador lista Assets, AssetsByType, AlertsBySeverity, OpenAlertsOverTime, VulnerabilitiesBySeverity, PatchCompliance e LicenseUsage. Carregue **LicenseUsage** e **PatchCompliance**.
4. Filtre no Power Query (por exemplo status \<> "compliant" ); um $filter no endereço seria recusado.
5. 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