Technical Information

This document covers the Lightyear to NetBox object mappings, API details, and configuration reference for the integration.

Lightyear to NetBox Object Mapping

Object Type Mapping Table

Lightyear Object	NetBox Object	Key Attributes
service_type	CircuitType	name (title-cased), slug
provider	Provider	name, slug
provider_account_number	ProviderAccount	account, provider
Service (summary + detail)	Circuit	cid (from details.provider_service_id), status, type, provider, provider_account, install_date, termination_date

---

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_KEY and LIGHTYEAR_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:

• lightyear
• discovered

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.