API

Screen: API and integration accounts (1/2)



Screen: API and integration accounts (2/2)

Everything you see and do in Hive is available in the REST API (OpenAPI 3.1, /api/v1 ). Other platforms use an integration account with a token sent as Authorization: Bearer <token> . The accounts are in Integrations › Integrations Center › API and integration accounts (needs permission to administer the API); the documentation of every route is in API documentation (Swagger).

Create an integration account per platform, choosing the data domains, the mode, the token validity, allowed IPs, mTLS and a request limit.

Switch (rotate) or revoke a token.

Turn on the CI webhook of an account, pause it, replace its secret and resend deliveries.

Browse and try every route in API documentation, and download openapi.json .

Click New integration account.

Give the account a name with lowercase letters, numbers and hyphens, like cmdb-servicenow , and say what it is for. The name appears in the audit trail of every call.

Choose the Data domains the account can use: Assets and details, Software and usage, Relationships and maps, Network, Cloud/virtualization/Kubernetes, Contracts and licenses, Vulnerabilities and insights, Alerts and events, Tickets and changes, Reports, Audit trail, People and identity, Device trust signal, Telemetry (OpenTelemetry) and Provider control plane. Choose the Mode: Read only (recommended) or Read and send (needed to import assets, change alerts or post tickets and changes). Optionally choose the CMDB model of the responses (Hive model, ServiceNow CSDM or DMTF CIM) and a Webhook for change notices (https).

Choose the Token validity (90, 180 or 365 days), optionally the Allowed IPs (ranges like 198.51.100.0/24), Require client certificate (mTLS) and the Request limit per minute (default 600; above it the API answers 429 with Retry-After).

Click Create account and token. Copy the token now: it is shown only once, and Hive keeps only a fingerprint of it. Test the token now checks it; Example call shows a ready request.

Columns: Integration account, Can access, Mode, Token (expiry; a warning 15 days before), Last use and CI webhook (On, Set up or Paused).

Switch token creates a new token (valid for 365 days); the old one keeps working for 7 days so the other platform can update, and then expires by itself. During that time the row shows "Two tokens valid during the switch (7 days)."

Revoke stops every call immediately and cannot be undone; to connect again, create a new account.

CI webhook: Receiving address, Turn on webhook, Pause/Resume, Replace secret, Send test, and the deliveries with Send again. Validate X-Hive-Signature : HMAC-SHA256 of "timestamp.body" with the secret shown once.

The same tab has Populate the CMDB of your platform, the Inbound routes (POST) and the Read proxy (optional), a small program in the DMZ that serves only GET routes.

API documentation (Swagger) opens the documentation of every route, grouped by area, with parameters, bodies and responses (needs permission to read integrations or administer the API).

Use the filter box to find an area (tag).

Try it out calls the API with your session, under your permissions. Only GET can be tried by default; tick Allow trying POST, PUT, PATCH and DELETE and confirm to run write requests for real (they go to the audit log).

Download openapi.json saves the contract to import in Postman or Bruno.

Remaining and RateLimit-Reset .

A revoked account cannot be restored.

Creating, switching and revoking need permission to administer the API.

Through the read proxy only read-only accounts work.

The webhook address must be public https; private addresses are refused.

There is no OAuth for integration accounts.

Populate your CMDB in 3 steps

Integrate with the GRCS

Grafana and Power BI

ITSM tickets, CMDB and approved changes

Any platform can keep its CMDB equal to Hive without a dedicated connector: an initial load, then only what changed, then change notices. Everything uses an integration account created in Integrations ›Integrations Center › API and integration accounts, with the scope Assets and details (and Software and usage to include the installed software).

Export all configuration items (CIs) at once, in the Hive model, ServiceNow CSDM or DMTF CIM.

Read only what changed since the last read, including removed items.

Receive a signed POST for each created, changed or removed CI.





GET /api/v1/cis/export?model=hive|csdm|cim&include=software returns all active CIs as NDJSON (one CI per line), as the file hive-cis.ndjson .

Or read in pages: GET /api/v1/cis?limit=500 and then GET /api/v1/cis?cursor=<nextCursor> until hasMore is false. limit goes up to 2000.

Each item has id , class , removed , updatedAt , attributes and, when asked, relationships . The model comes from the account (CMDB model of the responses) or from model= .

The last page of a read brings syncToken . Keep it.

Next time call GET /api/v1/cis?changed_since=<syncToken> : you get only new and changed CIs, and the retired ones with removed: true . Page with cursor as before and keep the new syncToken . changed_since=0 (or no parameter) is a full read.

Instead of polling, turn on the CI webhook of the account (column CI webhook › Set up, or Webhook for change notices in the wizard). Hive POSTs ci.created , ci.updated and ci.removed with the body {type, occurredAt, ci} and the headers X-Hive-Event , X-Hive-Delivery , X-Hive-Timestamp and X-Hive-Signature: sha256=<HMAC-SHA256 of "timestamp.body"> . Failures are retried from 30 s up to 12 h. Changes can also go to an event bus (Kafka, RabbitMQ, Service Bus, SNS, Pub/Sub).

Download the contract with Download openapi.json (or open API documentation (Swagger)) and import it in Postman or Bruno to get the full collection. Every call uses Authorization: Bearer <token> .



An invalid sync token returns 422 ( invalid-sync-token ); start over with a full read.

The export is not resumable; for very large bases, read in pages with cursor .

Webhook events go only to accounts with the Assets scope, from the moment it is turned on (no back-fill), and only for the subscribed assets when the account has a list.

The webhook address must be public https.

The contract ( /api/openapi.json ) requires sign-in unless the administrator made the API docs public.

API and integration accounts

Integrate with the GRCS

ITSM tickets, CMDB and approved changes

The GRCS brings from Hive only the assets that have an active risk or an open nonconformity: the asset record, open vulnerabilities, open alerts, business services and the control evaluation with evidence. It uses an integration account and the REST API; the GRCS card in Integrations › Integrations Center › Catalog (category GRC and risk) opens the account wizard with the right scopes.

Create the GRCS integration account with a webhook and a request limit.

Link each GRCS target to a Hive asset by its identifiers.

Subscribe the account to the assets that matter, by id or tag.

Read assets, findings, alerts, business services and compliance in batches, and receive events.

In Integrations Center › API and integration accounts, click New integration account (or Connect on the GRCS card). Choose the Data domains Assets and details, Vulnerabilities and insights, Alerts and events and Reports; Mode Read only (choose Read and send only if the GRCS writes its reference back). Fill in Webhook for change notices (optional) and Request limit per minute. The token is shown once.

POST /api/v1/assets/lookup with up to 500 identifiers ( id , externalRef , hwUuid , serial , fqdn , hostname , ip , or no type to try them in this order). Each answer says found , none or ambiguous (with candidates) and which identifier matched. IP is the last resort: an ambiguous match never links.

Optional: write the GRCS reference with PUT /api/v1/assets/import (source grcs , externalId = target id; needs Read and send). Later, GET /api/v1/assets?externalRef=grcs:<id> finds it.



PUT , PATCH or DELETE /api/v1/api-accounts//assets with asset ids or tags (for example the tag grcs ). The account itself can keep its list with its own token. With a list, the webhook and the events only cover the subscribed assets; without one, everything the scopes allow. Up to 5,000 assets and 100 tags per call, 50,000 entries per account.

GET /api/v1/assets//full — the asset with hardware, software, services, databases and relationships.

GET /api/v1/vulnerabilities/findings?asset=a,b,c and GET /api/v1/alerts?asset=a,b,c — up to 200 assets per call; with changedSince (24h, 7d or an ISO date) the list comes in change order and the next page is in the Hive-Next-Cursor header.

GET /api/v1/business-services?asset=a,b — services each asset is part of, its role (component or dependency) and whether it is a single point of failure.

GET /api/v1/assets//compliance or POST /api/v1/compliance/assets (up to 200 assets) — each control of ISO 27001, PCI DSS, LGPD/GDPR, HIPAA and CIS v8 that applies to the asset: atendido , parcial , nao_atendido or na , percentage and the measured evidence with its date.

The webhook receives vulnerability.opened , vulnerability.closed , vulnerability.risk_changed (severity, KEV or EPSS band changed) and compliance.changed , with subject = asset id and the X-Hive-Signature HMAC signature, besides the ci.* events. The same events can go to an event bus filtered by an asset tag.

Above the account limit the API answers 429 with Retry-After ; every response carries RateLimit-Limit , RateLimit-Remaining and RateLimit-Reset . The limit applies per core node. The parameter is changedSince here; the CI route uses changed_since .

API and integration accounts

Populate your CMDB in 3 steps

Compliance and hardening

Vulnerabilities

Screen: Grafana and Power BI

Hive serves ready datasets for BI tools under /api/v1/bi , read only: plain JSON for Grafana and an

OData v4 feed for Power BI. Both use an integration account token ( Authorization: Bearer <token> ), and

each dataset checks the read permission of its domain, so an account sees only what its scopes allow.

The Grafana and Power BI cards in Integrations › Integrations Center › Catalog (category BI) create

that account for you.

Create a read-only account for Grafana or Power BI in one click from the catalog.

List the datasets available to the account and read them as JSON or OData.

Build Grafana panels with time series ( from / to from the dashboard) and Power BI reports that

refresh from the feed.





Every dataset respects the profile's asset scope (sites, tags, groups) of whoever calls.

GET /api/v1/bi lists the datasets with title, columns, the permission, whether it is available to this caller, and the paths.

GET /api/v1/bi/<dataset> returns a JSON array of rows.

from and to : Grafana milliseconds ( $ , $ ) or ISO 8601; default the last 7 days. interval : 5m, 15m, 1h, 6h or 1d; without it, up to 2 days → 15m, up to 31 days → 1h, longer →1d (at most 5000 points).

limit (default 1000, up to 10000) and offset ; the next page is in the Link: <…>; rel="next" header.

@odata.nextLink . $filter and $orderby are refused ("Filter and sort in Power Query after loading the data").

Datasets the account cannot read are left out of the service document and of $metadata .

[Implementation="2.0"]) `` 3. The navigator lists Assets, AssetsByType, AlertsBySeverity, OpenAlertsOverTime, VulnerabilitiesBySeverity, PatchCompliance and LicenseUsage. Load LicenseUsage and PatchCompliance.

Only the Bearer token is accepted: no user and password (Basic), and no token in the address.

A dataset without the permission answers 403 ("This account cannot read this dataset."); without a token, 401.

The account rate limit applies (default 600 calls per minute); big Grafana dashboards with many panels count every panel.

The BI routes can also be served by the read proxy in the DMZ, with a read-only account.

The Power BI and Grafana screens are not part of Hive; their menu names may change between versions.

API and integration accounts

Reports and dashboards

Integrations Center