Skip to content

Site connector (edge) API

The site connector API manages edge connectors: the small service you run at a site for switches and access points that the cloud cannot reach directly or that cannot speak RadSec. It backs Network › Sites in the console. For installation, see Site connector.

A connector relays RADIUS from local devices to Airgate (over RadSec with its own client certificate, or over an HTTPS tunnel), relays CoA and Disconnect packets back to devices behind NAT, tunnels TACACS+ sessions, and forwards DHCP fingerprints for device profiling.

  • Admin routes are relative to /api/v1/t/{tenant}, where {tenant} is the tenant slug or ID. Reading needs policy:read; changes need policy:write (the same permissions as network devices). See API overview for authentication.
  • The connector’s own routes are under /edge/v1 from the root of your Airgate address. They use the connector’s credentials, not an API token. See Connector protocol.

Every change is audited with object type edge_connector (actions create, update, delete, issue_enrollment_token, cancel_enrollment_token, revoke, and, from the connector, enroll and renew_certificate). Audit details never contain tokens or keys.

To put a network device behind a connector, set its edge_id with the Network devices API. A connector serves exactly the enabled devices whose edge_id is its ID.

Route Permission Purpose
GET /edge-connectors policy:read List, with filters and sorting.
GET /edge-connectors/summary policy:read Counts and attention items.
POST /edge-connectors policy:write Create.
GET /edge-connectors/{id} policy:read One connector with its network devices.
PUT /edge-connectors/{id} policy:write Update.
DELETE /edge-connectors/{id} policy:write Delete.
POST /edge-connectors/{id}/enrollment-token policy:write Issue a one-time enrollment token.
DELETE /edge-connectors/{id}/enrollment-token policy:write Cancel the outstanding token.
POST /edge-connectors/{id}/revoke policy:write Drop the connector’s credentials.
GET /edge-connectors/{id}/jobs policy:read CoA relay job log.

List items have these fields; single-connector responses (create, get, update, revoke) also have nads.

{
"id": "3f1c2a64-6d1e-4b55-9a3e-0f8d2c1b7e10",
"tenant_id": "9eac1cf6-…",
"name": "London office",
"description": "Comms room, rack 2",
"sites": ["London office", "London annex"],
"enabled": true,
"radius_transport": "auto",
"dhcp_enabled": true,
"tacacs_enabled": true,
"status": "online",
"auth_mode": "certificate",
"enrollment_pending": false,
"enrollment_expires_at": null,
"cert_cn": "edge-3f1c2a64-6d1e-4b55-9a3e-0f8d2c1b7e10",
"cert_serial": "5a3f9c0e11d24b7a",
"cert_fingerprint": "8c1e…",
"cert_not_after": "2027-11-19T12:00:00Z",
"enrolled_at": "2026-11-19T12:00:05Z",
"last_seen_at": "2026-11-19T14:31:10Z",
"last_ip": "203.0.113.7",
"version": "1.0.0",
"hostname": "edge-london",
"stats": {"radius_received": 1832, "radius_replies": 1830, "radius_no_reply": 2,
"coa_jobs": 4, "coa_replies": 4, "dhcp_packets": 512, "tacacs_sessions": 12,
"upstream": "radsec", "upstream_healthy": true, "nads": 3, "uptime_seconds": 86400},
"nad_count": 3,
"attention": [],
"created_at": "2026-11-19T11:58:00Z",
"updated_at": "2026-11-19T12:00:05Z",
"nads": [
{"id": "b6d1…", "name": "sw-access-1", "ip_address": "10.0.0.5", "vendor": "Cisco", "coa_capable": true, "enabled": true}
]
}
Field Meaning
status disabled; not_enrolled (no credentials, no valid token); pending (no credentials, a valid enrollment token is outstanding); online (enrolled, last contact within 90 seconds); offline (enrolled, silent longer).
radius_transport auto (RadSec when the connector holds a RadSec certificate, else the HTTPS tunnel); radsec (same, with a warning in the connector’s configuration when it has no certificate); tunnel (always the HTTPS tunnel).
auth_mode "" (not enrolled), certificate (RadSec client certificate and API token) or bearer (API token only).
cert_* The current RadSec client certificate; empty in bearer mode.
stats Counters from the last heartbeat, plus uptime_seconds.
nad_count Network devices assigned to this connector, enabled or not.
attention Why the connector needs an administrator: not_enrolled, offline, cert_expiring (within 30 days or expired), radsec_without_cert, upgrade_pending (bearer mode although a RadSec certificate could be issued), upstream_unhealthy. Empty when all is well; disabled connectors never need attention.
last_ip Source address of the connector’s last call.

Permission: policy:read

Query Type Meaning
q string Matches name, description, hostname, last IP or any site.
status string online, offline, pending, not_enrolled or disabled.
auth_mode string certificate, bearer or none.
radius_transport string auto, radsec or tunnel.
version string Exact connector version; empty = never reported.
needs_attention boolean true or false.
sort string name (default), status, last_seen_at, created_at, version, nad_count, cert_not_after. Prefix - for descending.
limit, offset integer Paging. Default limit 50, at most 1000.

Filters combine with AND. An invalid value answers 400. Response 200: {"items": [Connector], "total": N}.

Terminal window
curl -s "$AIRGATE/api/v1/t/$TENANT/edge-connectors?needs_attention=true" \
-H "Authorization: Bearer $TOKEN"

Permission: policy:read

{
"total": 5,
"by_status": {"online": 1, "offline": 1, "pending": 1, "not_enrolled": 1, "disabled": 1},
"by_auth_mode": {"certificate": 0, "bearer": 2, "none": 3},
"by_transport": {"auto": 4, "radsec": 1, "tunnel": 0},
"versions": {"1.0.0": 1, "0.9.0": 1, "": 3},
"nads": 2, "nads_enabled": 2,
"attention": [{"id": "3f1c…", "name": "London office", "status": "offline", "reasons": ["offline"]}],
"attention_total": 2,
"pki_can_issue": true
}

attention lists at most 50 connectors; attention_total counts all. pki_can_issue says whether Airgate can issue RadSec client certificates to connectors (otherwise they enrol in bearer mode).

Permission: policy:write

Field Type Meaning
name string 1–128 characters, unique in the tenant. Required.
description string At most 1024 characters.
sites string[] Site names, at most 64 of 128 characters. Empty and duplicate entries are dropped.
enabled boolean Default true.
radius_transport string auto (default), radsec or tunnel.
dhcp_enabled boolean Accept DHCP fingerprints. Default true.
tacacs_enabled boolean Tunnel TACACS+. Default true.
Terminal window
curl -s -X POST "$AIRGATE/api/v1/t/$TENANT/edge-connectors" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"name":"London office","sites":["London office"],"radius_transport":"auto"}'

Response 201: the connector, with status not_enrolled and "nads": []. A duplicate name answers 409.

Permission: policy:write

Same fields, all optional; a field you leave out (or set to null) keeps its value, and "sites": [] clears the sites. Response 200: the connector.

Disabling a connector ("enabled": false) immediately refuses its API calls (403), RadSec connections, relayed requests and CoA relay, and closes its TACACS+ tunnels. "tacacs_enabled": false closes its TACACS+ tunnels too.

Permission: policy:write

Revokes the connector’s RadSec certificate, detaches its network devices (edge_id becomes null, so they become directly attached), deletes pending jobs and closes TACACS+ tunnels. Response 204.

Directly attached devices claim their addresses, so the delete answers 409 and changes nothing when a detached device would overlap a directly attached device of another tenant, or (for administrators who are not platform administrators) when a detached device has a range wider than IPv4 /16 or IPv6 /48. Reassign, narrow or delete those devices first.

POST /edge-connectors/{id}/enrollment-token

Section titled “POST /edge-connectors/{id}/enrollment-token”

Permission: policy:write

Field Type Meaning
ttl_hours integer Optional. 1–720, default 24.

Response 201. The token is shown only in this response:

{
"edge_id": "3f1c2a64-6d1e-4b55-9a3e-0f8d2c1b7e10",
"token": "et_4b1f0c…",
"expires_at": "2026-11-20T12:00:00Z",
"enroll_url": "https://airgate.contoso.com/edge/v1/enroll",
"command": "nac-edge enroll --url https://airgate.contoso.com --token et_4b1f0c…"
}
Terminal window
curl -s -X POST "$AIRGATE/api/v1/t/$TENANT/edge-connectors/3f1c…/enrollment-token" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"ttl_hours":24}'
  • Issuing a token replaces any outstanding one.
  • You can issue a token for an enrolled connector (for example after replacing its hardware). The current credentials keep working until the token is redeemed; then they are replaced, the old certificate is revoked and TACACS+ tunnels opened with the old credentials are closed.
  • A disabled connector answers 409.
  • When the Airgate address uses a certificate from a private CA that Airgate knows, the token also carries a pin of that CA (et_<48 hex>.<64 hex>). The connector then trusts the API only if the server’s chain contains the pinned certificate, so you do not need to copy the CA to the site.

DELETE /edge-connectors/{id}/enrollment-token

Section titled “DELETE /edge-connectors/{id}/enrollment-token”

Permission: policy:write

Cancels the outstanding token, if any. Response 204.

Permission: policy:write

Drops the connector’s API token and RadSec certificate (the certificate is revoked). The connector must be enrolled again with a new token. Existing RadSec connections are refused at the next request, and open TACACS+ tunnels are closed.

Field Type Meaning
cancel_token boolean Optional. Also cancel an outstanding enrollment token, so a leaked token cannot re-enrol the connector.

Response 200: the connector, with auth_mode "" (and status pending when a token is still outstanding).

Permission: policy:read

The CoA relay jobs of the connector, newest first. Jobs are kept 24 hours.

Query Type Meaning
status string pending, dispatched, done, failed or expired.
q string Matches device address, error text or verdict.
limit, offset integer Paging.
{"items": [{
"id": "7d0b…", "kind": "coa", "nad_address": "10.0.0.5:3799", "status": "done",
"error": "", "latency_ms": 12,
"verdict": "CoA-NAK", "error_cause": 503, "error_cause_name": "Session-Context-Not-Found",
"created_at": "2026-11-19T14:30:00.120Z", "expires_at": "2026-11-19T14:30:05.120Z",
"dispatched_at": "2026-11-19T14:30:00.140Z", "completed_at": "2026-11-19T14:30:00.170Z"
}], "total": 1,
"status_counts": {"pending": 0, "dispatched": 0, "done": 1, "failed": 0, "expired": 0}, "all": 1}

verdict is the device’s answer as reported by the connector (CoA-ACK, CoA-NAK, Disconnect-ACK, Disconnect-NAK, invalid, or "" when there was no answer). status_counts and all count the jobs matching q, regardless of the status filter and paging.

The connector (nac-edge) calls these routes on your Airgate address. They are documented so you can allow them through proxies and firewalls; you do not call them yourself. The connector needs outbound HTTPS to your Airgate address and, when it uses RadSec, outbound TCP to the RadSec address in its configuration (port 2083).

Except for enroll, every call carries Authorization: Bearer <api_token>, where the token is issued at enrollment. 401 means the token is missing or no longer valid (revoked, re-enrolled elsewhere, or the connector was deleted); 403 means the connector or tenant is disabled. Responses carry Cache-Control: no-store.

Method Path Purpose
POST /edge/v1/enroll Redeem an enrollment token (no bearer token).
GET /edge/v1/config Configuration, including the assigned network devices and their shared secrets. Supports ETag / If-None-Match.
POST /edge/v1/heartbeat Statistics and liveness, every 30 seconds by default. Returns the configuration ETag and whether to renew the certificate.
GET /edge/v1/jobs?wait=25 Long-poll for CoA relay and capture jobs (wait 0–50 seconds).
POST /edge/v1/jobs/{id}/result Result of a job.
POST /edge/v1/jobs/{id}/capture Upload the pcap of a capture job (at most 25 MB).
POST /edge/v1/dhcp Batched DHCP fingerprints (at most 2000 per call) for device profiling. 409 when dhcp_enabled is off.
POST /edge/v1/certificate Renew, or first obtain, the RadSec client certificate from a CSR.
POST /edge/v1/radius Tunnel transport: one RADIUS request in, its reply out.
GET /edge/v1/tacacs?nad=&port= TACACS+ tunnel (HTTP Upgrade nac-tacacs/1). At most 256 tunnels per connector.
Field Type Meaning
token string The enrollment token. Required. Single use.
hostname, version string Reported by the connector.
csr_pem string Optional PKCS#10 request for the RadSec client key, generated on the connector (ECDSA P-256 or P-384, or RSA 2048 or larger).

With a CSR, and when Airgate can issue RadSec client certificates, the connector enrols in certificate mode; otherwise in bearer mode.

{
"edge_id": "3f1c2a64-…", "tenant_id": "9eac1cf6-…", "tenant_slug": "contoso",
"name": "London office", "api_url": "https://airgate.contoso.com",
"api_token": "3f1c2a64-….9b0c…", "auth_mode": "certificate",
"certificate_pem": "-----BEGIN CERTIFICATE-----…", "ca_chain_pem": "-----BEGIN CERTIFICATE-----…",
"cert_serial": "5a3f9c0e11d24b7a", "cert_not_after": "2027-11-19T12:00:00Z",
"radius": {"transport": "radsec",
"radsec": {"address": "radius.contoso.com:2083", "server_name": "radius.contoso.com", "ca_pem": "…"}}
}

Errors: 400 (no token, bad CSR), 401 (unknown, expired or already used token), 403 (connector or tenant disabled), 503 pki_unavailable (the certificate could not be issued; the token is not used up, so retry).

The connector sends each device’s request unchanged and adds the original device address. Airgate identifies the tenant from the connector (its RadSec client certificate, CN edge-<connector ID>, or its tunnel credentials), never from a source IP, and the device by matching that address against the devices assigned to the connector (most specific prefix wins). The request is then handled exactly as if the device were directly connected. A device whose address is not assigned to the connector is dropped and reported as an unknown_device problem; a wrong shared secret is reported as bad_secret.

Other error codes you may see on connector routes: pki_unavailable (503), unavailable (503), upstream_error (502), upgrade_required (426), too_many_tunnels (429).

© 2026 Airowire Networks Pvt. Ltd. Airgate is a product of Airowire.Product · Release notes · Security