Network devices API
The network devices API manages the switches, access points, wireless controllers and other network access devices (NADs) that send RADIUS and TACACS+ to Airgate, the device groups that policies match on, and the vendor catalogue. It backs the console pages Network › Switches and APs and Network › Device groups.
Base path and permissions
Section titled “Base path and permissions”All routes are relative to /api/v1/t/{tenant}, where {tenant} is the tenant slug or ID. Every route needs a bearer token (see API overview).
| Permission | Grants |
|---|---|
policy:read |
Every GET route. |
policy:write |
Every other route. |
Lists use the standard envelope {"items": [...], "total": N} with ?q=&limit=&offset=&sort= (limit defaults to 50, at most 1000). Every change is written to the audit log (object types nad, nad_group); secrets never appear in responses, audit details or logs. Changes take effect for RADIUS within seconds on every node.
The RADIUS servers also call internal endpoints of this module to look up clients; those are not exposed on the public API.
Route summary
Section titled “Route summary”| Method | Path | Permission |
|---|---|---|
| GET | /nads |
policy:read |
| POST | /nads |
policy:write |
| POST | /nads/import |
policy:write |
| POST | /nads/bulk |
policy:write |
| GET | /nads/export.csv |
policy:read |
| GET | /nads/resolve |
policy:read |
| GET | /nads/{id} |
policy:read |
| PUT | /nads/{id} |
policy:write |
| PATCH | /nads/{id} |
policy:write |
| DELETE | /nads/{id} |
policy:write |
| GET | /nad-groups |
policy:read |
| POST | /nad-groups |
policy:write |
| GET | /nad-groups/{id} |
policy:read |
| PUT | /nad-groups/{id} |
policy:write |
| PATCH | /nad-groups/{id} |
policy:write |
| DELETE | /nad-groups/{id} |
policy:write |
| POST | /nad-groups/{id}/members |
policy:write |
| DELETE | /nad-groups/{id}/members/{nad_id} |
policy:write |
| GET | /nad-vendors |
policy:read |
The route POST /nads/{id}/radsec-cert (issue a RadSec client certificate for a device) is part of the Certificates and onboarding API.
Network devices
Section titled “Network devices”Device object
Section titled “Device object”{ "id": "4f1c2a9e-0b1d-4a51-9f65-3b9d2b2f6a10", "tenant_id": "9c1e5a77-…", "name": "core-sw1", "description": "Core switch, building A", "ip_address": "10.0.0.1", "vendor": "Cisco", "vendor_profile": "cisco-iosxe-switch", "radius_secret": "********", "tacacs_secret": "", "coa_capable": true, "coa_port": 1700, "radsec_enabled": false, "radsec_cert_cn": "", "require_message_authenticator": true, "edge_id": null, "group_ids": ["7d0e…"], "groups": ["Branch Switches", "Lab"], "attributes": {"Location": "HQ", "Floor": "2"}, "snmp": {"enabled": true, "version": "v2c", "port": 161, "community": "********", "read_arp": true}, "enabled": true, "created_at": "2026-10-29T08:00:00Z", "updated_at": "2026-10-29T08:00:00Z"}| Field | Meaning |
|---|---|
ip_address |
A single IP address or a CIDR block. A range that is exactly one block (192.0.2.0-192.0.2.255) is accepted. Host bits must be zero (10.1.1.0/24, not 10.1.1.1/24). Loopback, link-local, multicast, broadcast and unspecified addresses are refused. A directly attached device (see Address scope) may cover at most an IPv4 /16 or IPv6 /48. |
vendor |
RADIUS dictionary vendor (Aruba, Cisco, HP, Juniper, Arista, Fortinet, Ruckus, Meraki, Extreme, IETF and others; any name in dictionary_vendors of GET /nad-vendors). Case-insensitive; common aliases such as HPE are accepted. Default: the vendor profile’s vendor, else IETF. Policies see it as Device:Device-Type. |
vendor_profile |
Optional vendor catalogue ID (for example aruba-aoscx). Supplies the default vendor and coa_port. "" clears. |
radius_secret, tacacs_secret |
Shared secrets, stored sealed and returned as "********" (or "" when unset). Omitted or "********" keeps the stored value, "" clears, anything else replaces. At most 128 characters, no control characters, no leading or trailing spaces. |
coa_capable, coa_port |
Change of Authorization (RFC 5176). Default port: the vendor profile’s (Cisco 1700), else 3799. |
radsec_enabled, radsec_cert_cn |
RadSec (RADIUS over TLS). radsec_cert_cn is the expected client-certificate name, unique across Airgate; empty means the certificate CN must be the device ID. Names starting with edge- and UUIDs other than the device’s own ID are refused. |
require_message_authenticator |
Default true. Airgate drops Access-Requests from this device that lack Message-Authenticator (Blast-RADIUS / CVE-2024-3596 hardening). |
edge_id |
The site connector this device sits behind. Must be a connector of the tenant. null or "" clears. |
group_ids |
Explicit device group memberships. On input, replaces the explicit set. |
groups |
Read-only: names of all groups the device is in (explicit and matched). |
attributes |
Custom device attributes for policy (Device:*): at most 100; names up to 64, values up to 1024 characters. Replaced as a whole on update; null drops a key. |
snmp |
SNMP read settings for device profiling (below). |
enabled |
Packets from a disabled device are dropped. |
SNMP settings. {"enabled", "version" (v1 | v2c | v3, default v2c), "port" (default 161), "community", "username", "security_level" (noAuthNoPriv | authNoPriv | authPriv), "auth_protocol" (MD5 | SHA | SHA224 | SHA256 | SHA384 | SHA512), "auth_password", "priv_protocol" (DES | AES | AES192 | AES256 | AES192C | AES256C), "priv_password", "context_name", "zone", "read_arp", "force_read"}. v3 needs username; enabled v1 / v2c needs community. The object replaces the stored settings, except the three secrets, which keep their stored value when omitted or masked. "snmp": {} clears everything.
Address scope
Section titled “Address scope”Only devices identified by the source address of their packets claim their address across tenants. A device claims its address unless it has an edge_id, or it is RadSec-only (RadSec enabled with neither a RADIUS nor a TACACS+ secret).
- Devices behind a site connector are resolved by connector and address, so two customers’ sites may use the same private addresses.
- RadSec-only devices are identified by their client certificate.
- Address-claiming devices of different tenants can never overlap. A write that would cause an overlap returns
409with codeoverlapand the messageip_address … overlaps a network device of another tenant; devices behind shared or NATed addresses must use RadSec or an edge connector.
GET /nads
Section titled “GET /nads”Permission: policy:read
| Query parameter | Type | Meaning |
|---|---|---|
q |
string | An IP address returns the devices whose prefix contains it; a CIDR returns devices overlapping it; other text matches name, description, vendor, vendor profile and RadSec name. |
vendor |
string | Vendor (any accepted spelling). |
vendor_profile |
string | Catalogue ID. |
enabled |
boolean | Filter by state. |
edge_id |
UUID | Devices behind this site connector. |
group |
string | Group name or ID (effective membership). |
sort |
string | name (default), ip_address, vendor, created_at, updated_at; prefix - for descending. |
curl -s "$AIRGATE/api/v1/t/$TENANT/nads?q=10.0.0.77" -H "Authorization: Bearer $TOKEN"POST /nads
Section titled “POST /nads”Permission: policy:write
name and ip_address are required; all other device fields are optional.
curl -s -X POST "$AIRGATE/api/v1/t/$TENANT/nads" \ -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \ -d '{"name": "core-sw1", "ip_address": "10.0.0.1", "vendor_profile": "cisco-iosxe-switch", "radius_secret": "…", "coa_capable": true, "attributes": {"Location": "HQ"}}'Response 201: the device.
| Status / code | When |
|---|---|
400 bad_request |
Validation error, unknown group or site connector, range too wide. |
409 conflict |
Duplicate name; another device of the tenant in the same address scope has exactly this address; radsec_cert_cn already used. |
409 overlap |
The address overlaps an address-claiming device of another tenant. |
GET /nads/{id} · PUT /nads/{id} · PATCH /nads/{id} · DELETE /nads/{id}
Section titled “GET /nads/{id} · PUT /nads/{id} · PATCH /nads/{id} · DELETE /nads/{id}”Permission: policy:read (GET), policy:write (PUT, PATCH, DELETE)
PUT and PATCH behave the same: every field is optional and omitted fields are unchanged. Read-only fields are ignored, so a GET result can be sent back unchanged (masked secrets keep their stored values). Responses: 200 (GET, PUT, PATCH), 204 (DELETE), 404 for an unknown ID.
POST /nads/bulk
Section titled “POST /nads/bulk”Permission: policy:write
| Field | Type | Meaning |
|---|---|---|
ids |
array | 1–1000 device IDs. |
action |
string | enable, disable, delete, assign_edge or unassign_edge. |
edge_id |
UUID | Required for assign_edge; not allowed with other actions. |
Each device is changed exactly as the single-device routes would change it; one failing device does not stop the others.
{"action": "unassign_edge", "items": [{"id": "4f1c…", "name": "sw1", "status": "updated"}, {"id": "77aa…", "name": "", "status": "not_found"}], "total": 2, "updated": 1, "unchanged": 0, "deleted": 0, "not_found": 1, "failed": 0}status per ID is updated, unchanged, deleted, not_found or error (with error).
GET /nads/resolve
Section titled “GET /nads/resolve”Permission: policy:read
?ip=192.0.2.20. Shows which of the tenant’s devices serves an address and whether the RADIUS servers accept it as a client right now.
{"ip": "192.0.2.20", "nad": {"…": "device object"}, "radius_client": {"accepted": false, "reason": "device is reached through an edge connector"}}When accepted: {"accepted": true, "reason": "", "require_message_authenticator": true, "virtual_server": "nac", "shortname": "<device id>"}. Other reason values: device is RadSec-only (identified by its client certificate), device has no RADIUS shared secret, tenant is disabled, device is disabled, no network device of this tenant matches the address (nad is then null).
POST /nads/import
Section titled “POST /nads/import”Permission: policy:write
Imports devices from CSV: the file as the body (text/csv) or as the file part of multipart/form-data. Limits: 16 MiB and 20 000 rows; comma, semicolon or tab separated.
| Query parameter | Values | Meaning |
|---|---|---|
mode |
merge (default) or skip |
merge updates devices matched by name with the row’s non-empty cells; skip leaves existing devices untouched. |
dry_run |
true / false |
Validate everything (including cross-tenant overlap) and roll back. |
| Column (aliases) | Field |
|---|---|
name (device_name, nad_name) |
Name (required column). |
ip_address (ip, address, ip_prefix, subnet) |
Address. |
description |
Description. |
vendor (vendor_name) |
Vendor. |
vendor_profile (platform) |
Catalogue ID. |
radius_secret (radius_shared_secret, shared_secret, secret) |
RADIUS secret. |
tacacs_secret (tacacs_shared_secret) |
TACACS+ secret. |
coa_capable (coa_enabled, enable_coa), coa_port |
CoA. |
radsec_enabled (enable_radsec), radsec_cert_cn (radsec_cn) |
RadSec. |
require_message_authenticator (require_ma) |
Message-Authenticator requirement. |
enabled |
State. |
groups (nad_groups, device_groups) |
Group names separated by ;, | or new lines. Replaces explicit memberships. |
edge_id |
Site connector ID. |
attributes |
JSON object of attributes. |
attr:<name> |
One custom attribute. Any other unknown column also becomes a custom attribute. |
Booleans accept true/false, yes/no, 1/0, on/off, enabled/disabled. Empty cells never change a value. Each row is applied separately; a failing row is reported and skipped.
curl -s -X POST "$AIRGATE/api/v1/t/$TENANT/nads/import?mode=merge&dry_run=true" \ -H "Authorization: Bearer $TOKEN" -F "file=@switches.csv"{"dry_run": true, "mode": "merge", "rows": 7, "created": 2, "updated": 1, "unchanged": 0, "skipped": 0, "failed": 1, "errors": [{"line": 6, "name": "sw5", "error": "unknown network device group \"Nope\""}]}errors is capped at 500 (errors_truncated: true). A file over 16 MiB returns 413.
GET /nads/export.csv
Section titled “GET /nads/export.csv”Permission: policy:read
A CSV attachment with columns name, ip_address, description, vendor, vendor_profile, coa_capable, coa_port, radsec_enabled, radsec_cert_cn, require_message_authenticator, enabled, groups, edge_id, attr:<name>…. Secrets are never exported. The file re-imports unchanged.
Device groups
Section titled “Device groups”Group object
Section titled “Group object”{"id": "7d0e…", "tenant_id": "9c1e…", "name": "Branch Switches", "description": "", "group_format": "subnet", "value": "10.20.0.0/16, 10.21.0.0/16", "member_ids": ["4f1c…"], "member_count": 12, "members": [{"id": "4f1c…", "name": "br-sw1", "ip_address": "10.20.1.1", "explicit": true}], "created_at": "…", "updated_at": "…"}| Field | Meaning |
|---|---|
group_format |
list (default): device names, IDs, IPs, CIDRs and ranges. subnet: IPs, CIDRs and ranges only. regex: a regular expression matched against the device name and address. |
value |
Comma- or newline-separated items (or <br>-separated). A device whose prefix lies entirely inside a listed block is a member. |
member_ids |
Explicit members; they always count. |
member_count, members |
Effective members. members is returned by GET of one group, create, update and add-members. |
warnings |
On an update that renamed a group still referenced by name in policy conditions. |
GET /nad-groups
Section titled “GET /nad-groups”Permission: policy:read. Filters: q (name, description, value), group_format; sort = name, created_at or updated_at (prefix - for descending).
POST /nad-groups
Section titled “POST /nad-groups”Permission: policy:write
curl -s -X POST "$AIRGATE/api/v1/t/$TENANT/nad-groups" \ -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \ -d '{"name": "Lab", "group_format": "list", "value": "core-sw1, 10.0.0.7"}'Response 201. Names are unique case-insensitively (409).
GET /nad-groups/{id} · PUT /nad-groups/{id} · PATCH /nad-groups/{id} · DELETE /nad-groups/{id}
Section titled “GET /nad-groups/{id} · PUT /nad-groups/{id} · PATCH /nad-groups/{id} · DELETE /nad-groups/{id}”Permission: policy:read (GET), policy:write (others)
PUT / PATCH take the create fields, all optional; member_ids replaces the explicit set. DELETE returns 204, or 409 while the group is still referenced:
{"error": "network device group is still referenced", "code": "in_use", "referrers": [{"type": "enforcement_profile", "id": "…", "name": "Branch only"}, {"type": "service", "id": "…", "name": "Wired 802.1X"}]}POST /nad-groups/{id}/members
Section titled “POST /nad-groups/{id}/members”Permission: policy:write. {"nad_ids": ["…", "…"]} adds explicit members (idempotent). Response 200: the group.
DELETE /nad-groups/{id}/members/{nad_id}
Section titled “DELETE /nad-groups/{id}/members/{nad_id}”Permission: policy:write. Removes one explicit member. Response 204, or 404 when the device is not an explicit member.
Vendor catalogue
Section titled “Vendor catalogue”GET /nad-vendors
Section titled “GET /nad-vendors”Permission: policy:read
{"items": [ {"id": "cisco-iosxe-switch", "label": "Cisco IOS-XE switch (Catalyst 9k, IBNS)", "vendor": "Cisco", "vendor_id": 9, "dictionary": "dictionary.cisco", "coa_port": 1700, "coa_kinds": ["reauth", "disconnect", "bounce", "disable"], "redirect": "cwa", "redirect_attributes": ["Cisco-AVPair"], "role_attributes": ["Filter-Id", "Cisco-AVPair"], "vlan_attributes": ["Tunnel-Type", "Tunnel-Medium-Type", "Tunnel-Private-Group-Id"], "requires_event_timestamp": false, "requires_message_authenticator": true, "notes": "…"}], "total": 19, "dictionary_vendors": [{"name": "IETF", "vendor_id": 0}, {"name": "3com", "vendor_id": 43}]}Catalogue IDs: aruba-aos8, aruba-instant, aruba-aoscx, aruba-aoss, cisco-iosxe-switch, cisco-c9800, meraki-mr, meraki-ms, ruckus-smartzone, fortinet-fortigate, fortinet-fortiswitch, juniper-mist-ap, juniper-ex, arista-eos, arista-cvcue, ubiquiti-unifi, extreme-exos, extreme-xiq-ap, generic-rfc5176.
coa_kinds is a subset of reauth, disconnect, bounce, disable, attributes. coa_port: 0 means the platform has no RADIUS CoA. redirect is web-login, cwa, vendor-api, vendor-portal or none.