Automating Infrastructure Documentation with Obelinf

Your infrastructure documentation is only as valuable as it is current. When a device gets decommissioned, a subnet gets reallocated, or a cable run changes, the documentation needs to reflect that immediately. Manual updates through a web interface work fine when there are a handful of changes per week, but as your network grows and your team adopts continuous delivery workflows, the pace of infrastructure change outstrips what anyone can keep up with by hand. The gap between what is documented and what is actually deployed widens, and your source of truth starts to look more like a historical record than an accurate inventory that your team can trust for incident response and change planning.

The solution is automation. By connecting your infrastructure management platform to your provisioning tools, monitoring systems, CI/CD pipelines, and configuration management workflows, you can ensure that every change is documented at the moment it happens. The key that unlocks this automation is the API key, a programmatic credential that allows scripts, tools, and platforms to interact with your infrastructure data without requiring a human to log in through a browser. This article walks you through what API keys are, how to create them in Obelinf, and how to use them to build automated documentation workflows that keep your source of truth accurate in real time.

Creating an API Key in Obelinf

Create a separate API key for each integration or workflow. In your organization, open API & MCP, choose Create Key, and select the permission level that the integration needs. Use read only access for jobs that only inspect records. A workflow that creates or updates records needs write access, so keep that credential limited to the system that runs the workflow.

Obelinf generates your API key and displays it on screen only once. This is the only time the key is ever visible, so copy and store it in a secure location.

Using the API for Automated Documentation

With your API key created and stored, you can start building automated workflows. Every API request to Obelinf requires the key to be sent as a Bearer token in the Authorization header.

Most programming languages have HTTP client libraries that make working with the API straightforward. For example, you can use Python to create a new device record, the exact operation you would automate in a provisioning workflow:

import os
import requests

api_key = os.environ["OBELINF_KEY"]
org_slug = "my-org"
headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json",
}

new_device = {
    "name": "web-prod-01",
    "device_type": "server",
    "status": "active",
    "site_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
}

response = requests.post(
    f"https://api.obelinf.com/{org_slug}/devices",
    headers=headers,
    json=new_device,
)
response.raise_for_status()
device = response.json()
print(f"Created device {device['name']} with ID {device['id']}")

When you automate device creation in your provisioning pipeline, every server, switch, or firewall that gets deployed is automatically documented with no manual data entry required. The same approach applies to updating device status, managing cable connections, assigning IP addresses, and tracking circuit information.

Design a reliable sync workflow

Start by deciding which system owns each field. A cloud provider or provisioning system may be authoritative for instance identifiers and lifecycle state, while your infrastructure inventory may own internal naming, rack location, service ownership, or operational notes. If two systems can edit the same value, define which update wins and how conflicts are reviewed. Without that rule, automation can repeatedly overwrite a useful manual correction or preserve stale data indefinitely.

Make the integration safe to run more than once. Before creating a record, look for a stable identifier from the source system, such as an instance ID or a provisioning reference. Use that value to find the existing record and update it when appropriate. Avoid relying on a display name alone because names can be reused or changed. If the API or source system does not provide a reliable matching key for a resource, send the item to a review queue instead of creating duplicates based on a guess.

Treat a sync as a sequence of small, observable steps. Read the source data, validate required fields, compare it with current records, apply the planned changes, and report the outcome. Keep a run identifier and record the source, time, and result for each batch. When an item fails, capture enough detail to retry that item without replaying successful work. A clear summary should separate created, updated, unchanged, skipped, and failed records so an operator can see whether the inventory is complete.

Plan for lifecycle events explicitly. A missing resource in one API response does not always mean that it has been decommissioned. The source query could have failed, permissions may have changed, or a region may have been omitted. Mark a record for review after a confirmed retirement signal, then disconnect or archive related records according to your retention needs. Keep the source identifier and decommissioning event so the decision can be traced later.

Choose event driven updates or reconciliation

An event driven integration writes a record when a provisioning or change workflow runs. This keeps documentation close to the change and works well when the source reliably emits events. A scheduled reconciliation compares the current source inventory with documented records and can find missed events or manual drift. Many teams use both: events provide timely updates, and a periodic reconciliation reports anything that fell out of sync.

Keep the first version narrow. Start with one account, site, or resource type, and compare the resulting records with the source before enabling automatic writes. Add resource classes only after the mapping and ownership rules are understood. A small integration with clear error reporting is easier to trust than a broad job that quietly imports partial data.

Building Real World Automation Workflows

A common integration point is your infrastructure provisioning tooling. When a provisioning workflow creates a new server, you add a step that calls the Obelinf API to create a corresponding device record. This ensures that the device appears in your documentation at the same moment it becomes operational, not days or weeks later when someone gets around to updating the inventory manually. The same approach works for decommissioning: your decommissioning script can archive the device record and disconnect its interfaces in the same step that powers down the hardware.

For teams using configuration management tools, API keys enable automatic reconciliation of IP address assignments, VLAN configurations, and DNS records. Your configuration management system can query Obelinf for the current state of each resource and flag any discrepancies, turning your documentation into an active validation layer rather than a static record that drifts out of sync over time.

Security

API keys are scoped to the organization where they are created and can be configured for read only or write access. Keep each key in your CI or secret manager rather than in a source file, shell history, or log output. Do not print authorization headers when debugging requests. Restrict who can view or rotate the secret, and remove the key when the integration is retired.

Use different credentials for separate jobs so you can revoke one integration without interrupting the others. Give write access only to workflows that need to change records, and require review for broad imports or destructive lifecycle actions. Monitor failed authentication and unexpected write attempts, and rotate a credential if it may have been exposed. The changelog can help operators review mutations made through normal application workflows.

The Obelinf API supports common infrastructure records such as devices, sites, racks, interfaces, cables, IP addresses, subnets, VLANs, and circuits. Check the API reference for the supported operations and required fields for the resource you plan to automate. For teams that need programmatic access to their infrastructure documentation, API keys provide an authentication method that works with standard HTTP clients.

You can create your account for free at obelinf.com and start building the automated workflows that will keep your source of truth accurate without requiring anyone on your team to manually update device records or reconcile spreadsheets.