Technical Information
This document covers the Lightyear to NetBox object mappings, API details, and configuration reference for the integration.
Synchronized Object Types
The integration discovers and ingests four NetBox object types from the Lightyear service inventory:
| NetBox Object | Source | Notes |
|---|---|---|
CircuitType | Lightyear service type | Deduplicated by slug across all services |
Provider | Lightyear provider name | Deduplicated by slug across all services |
ProviderAccount | Lightyear provider account number | Only created when provider_account_number is present |
Circuit | Lightyear service (summary + detail) | Two-phase API fetch per service |
CircuitType
Lightyear service type values are transformed into NetBox CircuitType objects.
| Lightyear Field | NetBox Field | Transformation |
|---|---|---|
service_type | name | Underscores replaced with spaces, title-cased |
service_type | slug | Slugified (underscores replaced with hyphens) |
Example: wan_sd_wan → name Wan Sd Wan, slug wan-sd-wan
Duplicate service types across all services are deduplicated by slug before ingestion — only one CircuitType is created per unique slug value.
Provider
Each unique provider name in the Lightyear service list becomes a NetBox Provider.
| Lightyear Field | NetBox Field | Transformation |
|---|---|---|
provider | name | Used directly |
provider | slug | Slugified from name |
Providers are deduplicated by slug — if multiple services reference the same provider name, a single Provider entity is created.
ProviderAccount
Provider accounts are created when a service includes a provider_account_number value.
| Lightyear Field | NetBox Field | Transformation |
|---|---|---|
provider_account_number | account | Used directly |
provider | provider | Reference to the associated Provider entity |
ProviderAccounts are deduplicated using a composite key of provider_slug::account_number. Services without a provider_account_number do not generate a ProviderAccount.
Circuit
Circuit objects are built from a two-phase API fetch: a service summary call followed by a per-service detail call.
| Lightyear Field | NetBox Field | Source | Notes |
|---|---|---|---|
details.provider_service_id | cid | Detail call | Falls back to "Undefined" if absent |
status | status | Summary | See status mapping below |
service_type | type | Summary | Reference to CircuitType |
provider | provider | Summary | Reference to Provider |
provider_account_number | provider_account | Summary | Reference to ProviderAccount; omitted if no account |
start_date | install_date | Detail call | Parsed from ISO 8601 |
end_date | termination_date | Detail call | Parsed from ISO 8601; omitted if absent |
Circuit Status Mapping
| Lightyear Status | NetBox Status |
|---|---|
active | active |
inactive | offline |
in_progress | provisioning |
pending | planned |
cancelled | decommissioned |
| Any other value | planned |
API Details
Endpoints
| Endpoint | Purpose |
|---|---|
GET /developer/services/v1 | Retrieve full list of services (summary data) |
GET /developer/services/{id}/v1 | Retrieve detailed information for a single service |
Authentication
The Lightyear API uses HMAC-SHA256 signed requests:
- Signature:
HMAC-SHA256(api_secret, "path::body::timestamp") - Header:
Authorization: LY-HMAC Key=<api_key>,Timestamp=<unix_timestamp>,Signature=<signature> - Credentials required:
LIGHTYEAR_API_KEYandLIGHTYEAR_API_SECRET
Rate Limiting and Retries
| Parameter | Value |
|---|---|
| Max retries | 3 |
| Retry delays | 5s, 10s, 20s (exponential backoff, max 60s) |
| Retry-After header | Respected if present in 429 response |
If the rate limit is exceeded after all retries, the run is aborted with an error.
Policy Configuration
| Parameter | Required | Default | Description |
|---|---|---|---|
lightyear_api_key | Yes | — | Lightyear API key for authentication |
lightyear_api_secret | Yes | — | Lightyear API secret for HMAC signature generation |
lightyear_host | No | https://api.lightyear.ai | Override the Lightyear API base URL |
schedule | No | — | Cron expression controlling how often the agent runs; omit to run once and exit |
Tags and Metadata
All entities created or updated by the integration are tagged with:
lightyeardiscovered
These tags are applied to all object types (CircuitTypes, Providers, ProviderAccounts, and Circuits), making it straightforward to filter Lightyear-sourced data in the NetBox UI.