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.
Base path and permissions
Section titled “Base path and permissions”- Admin routes are relative to
/api/v1/t/{tenant}, where{tenant}is the tenant slug or ID. Reading needspolicy:read; changes needpolicy:write(the same permissions as network devices). See API overview for authentication. - The connector’s own routes are under
/edge/v1from 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.
Connectors
Section titled “Connectors”| 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. |
Connector object
Section titled “Connector object”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. |
GET /edge-connectors
Section titled “GET /edge-connectors”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}.
curl -s "$AIRGATE/api/v1/t/$TENANT/edge-connectors?needs_attention=true" \ -H "Authorization: Bearer $TOKEN"GET /edge-connectors/summary
Section titled “GET /edge-connectors/summary”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).
POST /edge-connectors
Section titled “POST /edge-connectors”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. |
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.
PUT /edge-connectors/{id}
Section titled “PUT /edge-connectors/{id}”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.
DELETE /edge-connectors/{id}
Section titled “DELETE /edge-connectors/{id}”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…"}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.
POST /edge-connectors/{id}/revoke
Section titled “POST /edge-connectors/{id}/revoke”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).
GET /edge-connectors/{id}/jobs
Section titled “GET /edge-connectors/{id}/jobs”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.
Connector protocol
Section titled “Connector protocol”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. |
POST /edge/v1/enroll
Section titled “POST /edge/v1/enroll”| 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).
How relayed RADIUS is identified
Section titled “How relayed RADIUS is identified”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).