Webex adapter

The Webex adapter reads locations, workspaces, devices and other JSON API resources into a sync project. Use it to compare your Webex inventory with your source of truth and sync the mapped attributes and peer relationships.

Webex is supported as a source only. Every data request uses GET. Service App authentication may POST to /v1/access_token to refresh credentials; the adapter never changes data in Webex. Requests must stay within the configured HTTPS origin, and redirects are rejected.

Authentication and permissions

Choose a fixed access token for short runs, or an authorized Service App for scheduled runs. Credentials are read exclusively from environment variables. The token_env, client_id_env, client_secret_env and refresh_token_env settings take literal variable names; {env: ...} references are accepted only in org_id and query parameter values. Provide them through your shell or secret manager; do not put their values in YAML.

Authentication	Required environment variables	Behavior
token (default)	WEBEX_TOKEN	Uses the supplied bearer token without renewal.
service_app	WEBEX_CLIENT_ID, WEBEX_CLIENT_SECRET, WEBEX_REFRESH_TOKEN	Obtains access at the start of the run, refreshes on expiry and retries once after HTTP 401.

For a Service App, change the source settings to:

source:
  name: webex
  settings:
    auth_method: service_app

An administrator must authorize the app before it can run. The Webex Service Apps documentation describes typical access-token and refresh-token lifetimes of 14 and 90 days. The adapter retains renewed credentials only in memory for the current process. Maintain valid credentials in your secret manager between scheduled runs; it does not persist rotated refresh tokens. An expired or revoked refresh token requires authorization again.

The inventory example needs administrator access with spark-admin:locations_read, spark-admin:workspaces_read and spark-admin:devices_read. These scopes grant read access to locations, workspaces and devices respectively. Other endpoints need their own read scopes. Check the Webex scope reference and the workspace API permissions before adding resources.

Sync locations, workspaces and devices

The inventory example maps three Webex resources to dedicated Infrahub kinds. Prepare the destination using the accompanying example schema before generating the project. The schema defines Text attributes for the inventory fields and optional relationships for workspaces without a location and devices without a workspace.

Infrahub kind	Webex endpoint	Identifier	Peer
WebexLocation	/v1/locations	webex_id from id	None
WebexWorkspace	/v1/workspaces	webex_id from id	location from locationId, referencing WebexLocation.
WebexDevice	/v1/devices	webex_id from id	workspace from workspaceId, referencing WebexWorkspace.

Each kind maps its display name. Devices also map serial number, product model, software, IP address and connection status. Webex IDs identify records, so changing a display name updates the existing destination node. The explicit order loads locations before workspaces and workspaces before devices, so their peers exist when devices are created. Keep the complete location and workspace mappings when importing devices that reference them.

infrahub-sync list --directory examples/
infrahub-sync generate --config-file examples/webex_workspaces_to_infrahub/config.yml
infrahub-sync diff --config-file examples/webex_workspaces_to_infrahub/config.yml

Set WEBEX_TOKEN and the destination's INFRAHUB_API_TOKEN through your secret manager or shell, and configure the destination address for your environment. Review the diff before approving sync with the same configuration. The example has no destination-retention flag: when a device disappears from Webex, the diff marks that device for deletion and leaves the other inventory nodes unchanged.

Known Infrahub deletion limitation

The existing Infrahub destination model implements create and update, but no persisted delete operation. A sync removes the deleted model from the current DiffSync store, while the node stays in Infrahub and is loaded again on the next run. This limitation belongs to infrahub-sync core and applies to every source adapter. The Webex example tests prove the one-device deletion diff; they do not claim that the Infrahub node is deleted. Review and reconcile removed inventory separately until core supports persisted deletion.

Connection settings

Set source.name: webex and configure the connection under source.settings.

Setting	Default	Meaning
url	https://webexapis.com	HTTPS origin; no path, query, fragment or embedded credentials.
auth_method	token	token or service_app.
token_env	WEBEX_TOKEN	Fixed-token environment variable name.
client_id_env	WEBEX_CLIENT_ID	Service App client-ID variable name.
client_secret_env	WEBEX_CLIENT_SECRET	Service App client-secret variable name.
refresh_token_env	WEBEX_REFRESH_TOKEN	Service App refresh-token variable name.
timeout	30	Positive timeout in seconds for each request.
retries	3	Retries per request for rate limits, server errors, timeouts and connection failures.
max_retry_delay	300	Maximum delay in seconds. A valid Retry-After above this value stops the run; default exponential retry delays are capped at this value.
page_size	100	Initial max value unless overridden by a resource or parameter.
org_id	Unset	Organization identifier, or an environment reference; omit to use the credential's organization.
params	{}	Query parameters applied across resources.
resources	{}	Extraction options keyed by schema-mapping model name.

For an organization ID from the environment:

source:
  name: webex
  settings:
    org_id:
      env: WEBEX_ORG_ID

Parameter names are unrestricted. Values can be strings, numbers, booleans, lists, {env: VARIABLE_NAME} or, for dependent resources, {parent: field.path}. Booleans serialize as true or false, and lists as comma-separated values. Query encoding preserves spaces and special characters. A resource parameter overrides a source parameter; null omits it. Organization scope is the exception: all nonempty orgId values must name the same organization as org_id. A different resource, endpoint or pagination organization is rejected. When no organization is configured, the first endpoint or pagination orgId is pinned for the client lifetime; later links must use the same organization. This learned ID is used for validation without adding orgId to other resource requests. Use one project per organization. A literal or environment-supplied orgId in query settings also establishes the project scope when org_id is unset; parent-derived organization IDs are rejected. For endpoints that reject orgId or max, omit those parameters in the resource with orgId: null or max: null.

Missing environment variables fail before any request, including token refresh. Pagination follows Webex Link headers until no next page remains, including empty intermediate pages. The adapter merges query parameters from the mapping path with the source and resource parameters, preserving repeated query keys and their values. Explicit source or resource parameters replace all path values of the same name. A null override removes that parameter from the first request and subsequent pages, even when a next-page link includes it. These fixed parameters remain on later pages when a next-page link omits them, including orgId. Initial before and after parameters are accepted in source settings, resource settings or endpoint queries, then removed before the first request to read the complete inventory. Webex continuation cursors still control subsequent pages. This prevents a configured start position from excluding earlier records. See Webex pagination for the response-header format.

The example uses page_size: 100 for locations and devices, and page_size: 1000 for workspaces. Choose an accepted size for each endpoint; a page-size setting never limits the total number of records loaded.

Resource settings and other endpoints

The mapping field of each schema mapping is its GET path, including /v1/. Fields, filters, Jinja2 transforms, identifiers and references follow the schema-mapping configuration.

Resource option	Default	Meaning
response_key	items	Dotted JSON key containing records; null selects a bare object or list.
params	{}	Overrides for source query parameters.
page_size	Connection default	Overrides the initial max value.
parent	Unset	Previously loaded mapping used to expand requests.
details	Unset	GET path expanded once per record; returned fields overwrite list fields.
read_only	false	Excludes source models from diff operations while keeping them available for references.

For example, a location-dependent request can retrieve workspaces once per location and then request the details of each workspace. The destination kinds and fields must exist in your schema. Replace the workspace resource options in a project that already loads the location mapping:

source:
  name: webex
  settings:
    resources:
      WebexWorkspace:
        parent: WebexLocation
        params:
          locationId:
            parent: id
        details: /v1/workspaces/{id}
        page_size: 1000

Set order: [WebexLocation, WebexWorkspace, WebexDevice] when using parent. Parent request dependencies are not inferred from these resource options. The parent fields are the loaded Webex record fields, so id is the Webex location ID. Path placeholders such as {id} or {address.country} are URL-escaped; a mapping path can use them to address a resource under each parent. Per-parent 404 responses skip that absent resource, while empty parent fields skip the request with a warning.

For a fixed filter on the Calling List Workspaces endpoint, set resources.WebexWorkspace.params: {type: meetingRoom}. The parameter is sent on every page, and the adapter loads the set Webex returns. If devices reference other workspace types, keep those workspaces available too or change the device mapping accordingly.

For an endpoint returning one object, set response_key: null and params: {max: null}. Records without their own ID receive an internal source identifier; map the destination identifiers explicitly. Details load before the shared filters and transforms.

A scalar reference value is already the peer's sync identifier, as in the inventory project's locationId and workspaceId. A native dict such as {{ {'id': locationId} }} instead resolves the peer by its source local_id; an absent dict reference raises an error. Choose the form that matches the identifiers in the peer mapping.

Failure handling

Failure	Result and action
HTTP 401	Fixed-token authentication fails; Service App authentication refreshes once, then fails if still unauthorized. A refresh failure names Webex and the original data endpoint as well as the OAuth failure.
HTTP 403	Reports insufficient permission for the resource; check read scopes and administrator authorization.
HTTP 400	Reports the endpoint, status and Webex message after redacting credentials, bearer values and URLs; check the named query parameter. Other response fields and raw bodies are excluded.
Other rejected response	Reports the resource and status; check endpoint and query settings.
HTTP 429	Waits for Retry-After, then retries up to retries; persistent limits stop the run. A valid Retry-After longer than max_retry_delay stops the run without waiting. Missing or invalid headers use exponential retry delays capped at max_retry_delay.
Timeout, connection failure or HTTP 5xx	Retries with bounded attempts and default exponential retry delays capped at max_retry_delay, then stops with resource context.
Missing response key or malformed JSON	Stops rather than treating the resource as empty. A missing-key error names the endpoint and configured key, for example /v1/devices: missing configured response key records.
Redirect, external pagination link or pagination cycle	Stops; credentials are never forwarded to another origin.
Conflicting organization IDs	Stops before HTTP for conflicting settings, or before following a conflicting endpoint or pagination link.

Errors and logs exclude credentials, raw response bodies and underlying request-exception text. Each attempted HTTP request logs a debug-level event with a cumulative requests counter, including retries, OAuth requests and failed parent requests. A Webex mapping requests event reports the mapping count and client-wide total_requests, including when a mapping fails. Incremental change tracking is not implemented for Webex.