Skip to content

Change of Authorization (CoA) API

The CoA API sends RFC 5176 dynamic-authorization requests (CoA and Disconnect) to switches, controllers and access points, and reads the log of every attempt. It is what the Re-authenticate, Disconnect, Bounce port and Disable port actions in the console’s Sign-in log, Connected now and device pages call.

All routes are relative to /api/v1/t/{tenant}, where {tenant} is the tenant slug or ID. See API overview for authentication.

Route Permission
POST /coa monitor:coa, plus policy:write when the request has attributes
POST /coa/preview monitor:read
GET /coa/log monitor:read
GET /coa/log/counts monitor:read
GET /coa/log/{id} monitor:read
GET /coa/vendors policy:read
  • Every packet carries Event-Timestamp and a Message-Authenticator keyed with the device’s RADIUS shared secret. API results and the log always show the Message-Authenticator value masked as ********.
  • Airgate sends over UDP with a 3-second timeout and up to 2 retransmissions of the same packet. For a device behind a site connector, the connector relays the packet.
  • Responses are validated (identifier, Response Authenticator, Message-Authenticator). A response with a wrong secret is discarded.
  • A device with a wrong shared secret, or one that rejects the Message-Authenticator, stays silent. Airgate reports that as timeout, never as a NAK.
kind Packet Meaning
reauth CoA-Request Re-run authentication for the session.
disconnect Disconnect-Request End the session.
bounce CoA-Request Bounce the switch port.
disable CoA-Request Shut the switch port.
attributes CoA-Request Push new attributes (role, ACL, VLAN) to the session.

Aliases are accepted in any case, with _ or -: reauthenticate, re-authenticate, reauthenticate-session mean reauth; terminate, terminate-session, disconnect-request mean disconnect; bounce-port, port-bounce, bounce-host-port, bounce-switch-port mean bounce; disable-port, disable-host-port, disable-switch-port mean disable; attribute, custom, change, role-change, generic mean attributes. Results and the log always show the canonical kind.

When the device’s vendor template has no reauth or bounce packet (for example Aruba AOS 8, Aruba Instant, Ruckus, Meraki MR, Arista), Airgate sends a Disconnect-Request instead and adds a note; the client re-authenticates when it reconnects. A missing disable or attributes template is an error.

  • The network device must be enabled, have CoA turned on (coa_capable) and a RADIUS shared secret.
  • coa_port is the destination port (default 3799); 0 uses the template’s default port.
  • The vendor template comes from the device attribute CoA-Template, else the device’s vendor profile, else its vendor name, else generic-rfc5176.
  • Optional device attributes: CoA-MAC-Format (one of the mac_format values below) and CoA-Address (send to this IP instead of the NAS address, for example an Aruba Instant virtual controller).

Permission: monitor:coa. A request with a non-empty attributes list also needs policy:write; otherwise it answers 403.

Sends one packet per target, in parallel, and returns when every target has answered or timed out (about 9 seconds per target at most; the request is bounded to 60 seconds).

Field Type Meaning
kind string See Kinds. Required unless profile_id is set.
mac string MAC address in any notation. Targets every active session of the device, newest first, at most 8.
session_id UUID Targets exactly this session. With mac too, the MAC must be the session’s.
profile_id UUID A RADIUS CoA enforcement profile of the tenant. The profile decides the kind and attributes. Another profile type answers 400.
attributes array [{"name", "op", "value"}] merged into the packet. Needs policy:write. Required for kind: attributes without a profile. At most 256.
reason string Free text, at most 1000 characters, stored in the log and the audit log.

Either mac or session_id is required.

Attribute operators: "", = or += append; := replaces template attributes of the same name; -= removes them. value may contain %{…} references resolved against the target session. Names are RADIUS dictionary names; Name:N sets an RFC 2868 tag (for example Tunnel-Private-Group-Id:1). Encrypted attributes such as Tunnel-Password are refused.

Terminal window
curl -s -X POST "$AIRGATE/api/v1/t/$TENANT/coa" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"kind":"reauth","mac":"3c:22:fb:12:34:56","reason":"helpdesk ticket 42"}'

Response 200. ok is true when at least one target acknowledged.

{
"ok": true,
"results": [{
"session_id": "ba87f442-…", "nad": "sw1", "nad_id": "3bcfe9fb-…",
"nad_address": "10.0.0.5:3799", "edge_id": null,
"packet": "CoA-Request", "code": "CoA-ACK", "kind": "reauth",
"mac": "3c:22:fb:12:34:56", "username": "alice@contoso.com",
"vendor_template": "cisco-iosxe-switch", "profile_id": null, "profile_name": "",
"sent": [
{"name": "Message-Authenticator", "op": "=", "value": "********"},
{"name": "Calling-Station-Id", "op": "=", "value": "3C-22-FB-12-34-56"},
{"name": "Cisco-AVPair", "op": "=", "value": "subscriber:command=reauthenticate"},
{"name": "Event-Timestamp", "op": "=", "value": "1795000000"}
],
"received": [], "notes": [], "error": "",
"latency_ms": 4, "attempts": 1, "log_id": "e20fe94b-…"
}]
}
Result field Meaning
packet CoA-Request or Disconnect-Request (empty when the attempt failed before a packet was chosen).
code CoA-ACK, CoA-NAK, Disconnect-ACK, Disconnect-NAK, timeout or error.
error_cause RFC 5176 Error-Cause name of a NAK, such as Session-Context-Not-Found. Omitted when empty.
sent, received Attributes sent and received, decoded.
latency_ms, attempts Time to the answer (or to giving up) and transmissions made (1–3).
edge_id Site connector that relayed the packet; null for direct UDP.
vendor_template Template used; see GET /coa/vendors.
error Why a timeout or error happened, for example no response from 10.0.0.5:3799 after 3 attempt(s): wrong shared secret, NAS unreachable / ACL, or dynamic authorization not enabled.
notes Non-fatal remarks: a reauth sent as a disconnect, an identifier left out, an unknown vendor using the generic template.
log_id The CoA log entry of this attempt.

Errors (nothing sent): 400 for an invalid body, kind, MAC, attribute or operator, more than 256 attributes, kind: attributes without attributes, neither mac nor session_id, or a profile that is not a RADIUS CoA profile; 403 for attributes without policy:write; 404 session not found, no active session for <mac> or enforcement profile not found; 409 profile_unusable when a secret value of the profile cannot be decrypted; 503 when the session store or policy engine is unavailable. The 404, 409 and 503 failures are still written to the CoA log with code: "error".

Each request is audited (action coa, object type endpoint or session).

Permission: monitor:read

Same body as POST /coa. Resolves the targets, devices and templates and builds the packets, but sends nothing and writes no log. Each result has code "" for a packet that would be sent, or error with the reason when it could not be built.

Terminal window
curl -s -X POST "$AIRGATE/api/v1/t/$TENANT/coa/preview" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"kind":"bounce","mac":"3c:22:fb:12:34:56"}'

With profile_id, Airgate renders a RADIUS CoA enforcement profile:

  • The kind comes from the profile’s template: Disconnect sends a Disconnect-Request, Reauthenticate a reauth, Bounce-Port a bounce, Disable-Port a disable, anything else (Custom) pushes attributes.
  • A profile with attributes is the packet: each attribute value is expanded with %{…} against the target session; an empty value leaves the attribute out with a note.
  • A profile without attributes uses the device’s vendor template for the kind, or the template named in the profile’s Vendor setting.
  • The profile’s delay applies only to CoAs Airgate sends after a sign-in; POST /coa is always immediate.
  • A packet with no session identifier at all (User-Name, Calling-Station-Id, Acct-Session-Id, Framed-IP-Address, NAS-Port, NAS-Port-Id, audit-session-id and similar) is not sent.

Permission: monitor:read

Newest first. Response 200: {"items": [LogEntry], "total": N}.

Query Type Meaning
limit, offset integer Paging. Default limit 50, at most 1000.
q string Case-insensitive match on MAC, username, device name, reason, error or profile name.
mac string A full MAC in any notation, or a fragment.
session_id, nad_id, edge_id UUID Only these. edge_id = attempts relayed by that site connector. A malformed UUID answers 400.
code string ack (CoA-ACK and Disconnect-ACK), nak, failed (everything but an ACK), or an exact code such as timeout, error, CoA-NAK.
kind string A kind or alias. Unknown kinds answer 400.
source string manual (console or API), api (another Airgate module, synchronous), async (sent automatically after a sign-in, posture or device-type change).
origin string The requesting module: admin, radius, posture, profiler, guest, onboard, insight.
from, to string RFC 3339, YYYY-MM-DD, YYYY-MM-DDTHH:MM[:SS] (UTC) or Unix seconds or milliseconds. from is inclusive, to exclusive.
Terminal window
curl -s "$AIRGATE/api/v1/t/$TENANT/coa/log?code=failed&from=2026-11-01" \
-H "Authorization: Bearer $TOKEN"

A log entry has the result fields above plus id, at, source, actor (the administrator’s email or API client name for manual, system for async), reason, origin, delay_ms and error_cause (always present, "" when none). Entries whose target could not be resolved have code: "error", an empty packet and nad, and the reason in error.

CoA log entries are kept for the tenant’s retention period (default 30 days).

Permission: monitor:read

Counts per outcome for the same filters as GET /coa/log (code, limit and offset are ignored).

{"all": 42, "ack": 30, "nak": 4, "timeout": 6, "error": 2, "failed": 12}

failed is all minus ack.

Permission: monitor:read

One log entry. 404 when it does not exist in the tenant; 400 for a malformed ID.

Permission: policy:read

The template catalogue, in display order. Response 200: {"items": [Template], "total": N}.

{
"key": "cisco-iosxe-switch",
"label": "Cisco IOS-XE switch (Catalyst 9k, IBNS)",
"aliases": ["Cisco", "Cisco IOS", "Cisco IOS-XE", "Cisco Catalyst", "Catalyst"],
"default_port": 1700,
"event_timestamp": "sent",
"mac_format": "upper-hyphen",
"kinds": {
"reauth": {"packet": "CoA-Request", "attributes": [
{"name": "Calling-Station-Id", "value": "${s.calling_station_id}"},
{"name": "Cisco-AVPair", "value": "audit-session-id=${s.audit_session_id}", "optional": true},
{"name": "Cisco-AVPair", "value": "subscriber:command=reauthenticate"}]}
},
"radius_coa": true,
"notes": "Every identifier sent must match (NAK 407). …",
"supported_kinds": ["attributes", "bounce", "disable", "disconnect", "reauth"]
}
Field Meaning
event_timestamp required (the device drops packets without it or outside its time window, so keep NTP in sync) or sent.
mac_format Calling-Station-Id notation used when the session’s raw value is unknown: colon, hyphen, upper-hyphen, upper-colon, nodelim, upper-nodelim, dot.
confidence verify-lab for templates not yet verified on a device; omitted otherwise.
radius_coa false for platforms without RADIUS dynamic authorization (Ubiquiti UniFi): every CoA to them fails with an explanation.

Template placeholders: ${s.calling_station_id}, ${s.user_name}, ${s.nas_ip}, ${s.nas_identifier}, ${s.nas_port}, ${s.nas_port_id}, ${s.acct_session_id}, ${s.audit_session_id}, ${s.framed_ip}, ${s.called_station_id}, ${bounce_seconds|12}. An attribute whose placeholder is empty is left out.

Template key Default port Kinds
aruba-aos8 3799 disconnect, bounce, attributes
aruba-instant 3799 disconnect, attributes
aruba-aoscx 3799 disconnect, bounce, attributes
aruba-aoss 3799 disconnect, bounce, attributes
cisco-iosxe-switch 1700 all five
cisco-c9800 1700 reauth, disconnect, attributes
cisco-asa 1700 disconnect, attributes
meraki-mr 3799 reauth, disconnect, attributes
meraki-ms 3799 reauth, disconnect, bounce, attributes
ruckus-smartzone 3799 disconnect, attributes
fortinet-fortigate 3799 disconnect
fortinet-fortiswitch 3799 all five
juniper-mist-ap 3799 reauth, disconnect, attributes
juniper-ex 3799 disconnect, bounce, attributes
arista-eos 3799 disconnect, bounce, attributes
arista-cvcue 3799 disconnect, attributes
extreme-exos 3799 disconnect, attributes
extreme-xiq-ap 3799 disconnect, attributes
h3c-comware 3799 disconnect, bounce, disable, attributes
trapeze 3799 disconnect, attributes
motorola-wing 3799 disconnect, attributes
ubiquiti-unifi none none
generic-rfc5176 3799 disconnect, attributes

Every attempt, including failures before transmission, is published as the event coa.sent, which you can receive with a webhook.

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