Skip to content

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.

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.

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.

{
"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.

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 409 with code overlap and the message ip_address … overlaps a network device of another tenant; devices behind shared or NATed addresses must use RadSec or an edge connector.

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.
Terminal window
curl -s "$AIRGATE/api/v1/t/$TENANT/nads?q=10.0.0.77" -H "Authorization: Bearer $TOKEN"

Permission: policy:write

name and ip_address are required; all other device fields are optional.

Terminal window
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.

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).

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).

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.

Terminal window
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.

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.

{"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.

Permission: policy:read. Filters: q (name, description, value), group_format; sort = name, created_at or updated_at (prefix - for descending).

Permission: policy:write

Terminal window
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"}]}

Permission: policy:write. {"nad_ids": ["…", "…"]} adds explicit members (idempotent). Response 200: the group.

Permission: policy:write. Removes one explicit member. Response 204, or 404 when the device is not an explicit member.

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.

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