Ceburu Service Graph Access Guide

Created by niharika Velidhi, Modified on Thu, 9 Apr at 2:16 PM by niharika Velidhi

This document explains how Manage API Keys works in Ceburu, what types of keys are available, how they should be used for Service Graph style integrations, and what the API responses look like in practice.

Purpose:

Manage API Keys is used to generate secure machine-to-machine API keys for external integrations.

Current intended use:

ServiceNow Service Graph style data pulls
external CMDB or sync applications
scheduled pull-based integrations

These keys are not user login tokens.

What Manage API Keys Does:

The Manage API Keys page allows you to:

create a new API key
choose the integration type
choose the access scope
define allowed endpoints
set expiry
set a rate limit
regenerate a key
revoke a key

Important:

the raw key is shown only once
it must be copied and stored immediately
if lost, it must be regenerated

Supported Integration Type:

Current supported type:

ServiceNow Graph Connector

This key type is intended for external systems that pull data from Ceburu APIs.

API Key Types:

There are two main scope types.

1. All Customer Networks

This is the default and recommended option.

Meaning:

the key is scoped to the customer
the key can access all networks under that customer
the external integration can pull data across all accessible networks

Use this when:

one customer has multiple networks
one external integration should access all of them
one shared source is preferred for the customer

2. Specific Network Only

Meaning:

the key is restricted to one network
the external integration can only access that network’s data
attempts to access another network are rejected

Use this when:

strict network isolation is required
different connector instances are used per network
access must be limited by design

Recommended Usage Model:

Recommended model:

one customer-scoped API key per customer
one external integration can access all the customer’s networks
data pulls should still be performed per network for clarity and control

This is preferred over:

one key per network by default
duplicated key management for the same customer

How the Scope Is Determined:

The key scope is determined through the discovery endpoint:

GET /integrations/servicegraph/networks/

This endpoint returns:

customer_id
scope
scoped_network_id
networks

Meaning of the fields

scope = "customer"
- the key is customer-scoped
- all returned networks are accessible
scope = "network"
- the key is restricted to one network
scoped_network_id = null
- all customer networks are allowed
scoped_network_id = <id>
- only that network is allowed

API Endpoints Available for This Key Type:

1. Discover accessible networks

GET /integrations/servicegraph/networks/

2. Pull network map

GET /integrations/network-map/by-customer/
 GET /integrations/network-map/by-customer/?network_id=<id>

3. Pull network map with latest health

GET /integrations/network-map/latest-health/by-customer/
 GET /integrations/network-map/latest-health/by-customer/?network_id=<id>

4. Pull AIOps devices

GET /integrations/aiops/devices/by-customer/
 GET /integrations/aiops/devices/by-customer/?network_id=<id>

5. Pull AIOps devices with specs and interfaces

GET /integrations/aiops/devices/full/by-customer/
 GET /integrations/aiops/devices/full/by-customer/?network_id=<id>

Default Allowed Endpoints:

For ServiceNow Graph Connector, the default allowed endpoints are:

/integrations/servicegraph/networks/
/integrations/network-map/by-customer/
/integrations/network-map/latest-health/by-customer/
/integrations/aiops/devices/by-customer/
/integrations/aiops/devices/full/by-customer/

If a key tries to call an endpoint outside this list, the request is rejected.

Actual API Response Examples:

These examples are based on the current implemented API response structure and the tested behavior.

1. Discovery response for All Customer Networks

{
  "customer_id": 24,
  "scope": "customer",
  "scoped_network_id": null,
  "networks": [
    {
      "id": 2,
      "name": "Production",
      "probe_name": "Probe A",
      "probe_ip": "10.10.10.2",
      "network_group_id": 5,
      "customer_id": 24
    },
    {
      "id": 57,
      "name": "Branch Office",
      "probe_name": "Probe B",
      "probe_ip": "10.10.10.57",
      "network_group_id": 6,
      "customer_id": 24
    }
  ]
 }

Meaning:

the key belongs to customer 24
the key is customer-scoped
both networks 2 and 57 are accessible

2. Discovery response for Specific Network Only

{
  "customer_id": 24,
  "scope": "network",
  "scoped_network_id": 57,
  "networks": [
    {
      "id": 57,
      "name": "Branch Office",
      "probe_name": "Probe B",
      "probe_ip": "10.10.10.57",
      "network_group_id": 6,
      "customer_id": 24
    }
  ]
 }

Meaning:

the key is restricted to network 57
only that network is accessible

3. Network map response example

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "netmap": {
        "id": 101,
        "network_id": 2,
        "host": "server-01",
        "hostip": "10.0.0.10",
        "vendor": "Dell",
        "os": "Windows Server",
        "status": "up",
        "overallseverity": "low"
      },
      "networkdetails_id": 2,
      "networkname_id": 5,
      "networkname": "Production",
      "customer_id": 24,
      "scope": "customer"
    }
  ]
 }

Meaning:

results contains device/network-map records
scope reflects how the key is being used
networkdetails_id is the network used for further filtering/reference

4. Latest health response example

The exact payload varies by latest health record, but the structure is returned per matching network/device record and includes the latest health details associated with the network map/device.

Example reference shape:

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "netmap_id": 101,
      "network_id": 2,
      "host": "server-01",
      "hostip": "10.0.0.10",
      "latest_health": {
        "cpu": 42,
        "memory": 68,
        "disk": 71,
        "status": "healthy",
        "timestamp": "2026-04-08T15:10:00Z"
      },
      "customer_id": 24
    }
  ]
 }

5. AIOps devices response example

The exact fields depend on the device records present in the environment, but the endpoint returns paginated device data for the allowed customer/network scope.

Example reference shape:

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 501,
      "network_id": 2,
      "customer_id": 24,
      "hostname": "server-01",
      "ip_address": "10.0.0.10",
      "device_type": "server",
      "vendor": "Dell",
      "os": "Windows Server"
    }
  ]
 }

6. AIOps devices full response example

This endpoint returns a richer payload, including specs and interfaces when available.

Example reference shape:

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 501,
      "network_id": 2,
      "customer_id": 24,
      "hostname": "server-01",
      "ip_address": "10.0.0.10",
      "device_type": "server",
      "vendor": "Dell",
      "os": "Windows Server",
      "specs": {
        "cpu_model": "Intel Xeon",
        "memory_gb": 32
      },
      "interfaces": [
        {
          "name": "eth0",
          "mac": "00:11:22:33:44:55",
          "ip": "10.0.0.10"
        }
      ]
    }
  ]
 }

Negative Response Examples:

1. Wrong network for a network-scoped key

{
  "error": "This API key is restricted to a different network."
 }

2. Calling an endpoint not in allowed_endpoints

{
  "detail": "This API key is not allowed to access the requested endpoint."
 }

3. Invalid key

{
  "detail": "Invalid API key"
 }

Manage API Keys UI Behavior:

Current frontend behavior:

Generate API Key opens a modal
user selects integration type
user selects scope:
- All customer networks
- one specific network
user can review/edit allowed endpoints
user can set expiry
user can set rate limit
generated key is shown once
Copy & Close copies the key and dismisses the prompt
existing keys show:
- name
- integration type
- scope
- status
- rate limit
- expiry
- created time

Regenerate and Revoke Behavior:

Regenerate

When a key is regenerated:

the old key becomes invalid
a new raw key is created
the new key must be stored again

Revoke

When a key is revoked:

it immediately stops working
requests using that key will fail

Expiry and Rate Limits:

Each key supports:

expiry
per-minute rate limit

Behavior:

expired keys are rejected
rate-limited requests return an error and should be retried later

Best Practices:

use All customer networks unless strict isolation is required
use Specific network only only for restricted deployments
keep allowed endpoints limited to the actual connector needs
rotate keys when needed
revoke unused keys
store raw keys securely
validate the discovery endpoint first before testing other APIs