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.
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. 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 |
How Airgate sends a CoA
Section titled “How Airgate sends a CoA”- Every packet carries
Event-Timestampand aMessage-Authenticatorkeyed with the device’s RADIUS shared secret. API results and the log always show theMessage-Authenticatorvalue 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.
Network device requirements
Section titled “Network device requirements”- The network device must be enabled, have CoA turned on (
coa_capable) and a RADIUS shared secret. coa_portis the destination port (default3799);0uses 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, elsegeneric-rfc5176. - Optional device attributes:
CoA-MAC-Format(one of themac_formatvalues below) andCoA-Address(send to this IP instead of the NAS address, for example an Aruba Instant virtual controller).
POST /coa
Section titled “POST /coa”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.
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).
POST /coa/preview
Section titled “POST /coa/preview”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.
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"}'RADIUS CoA profiles
Section titled “RADIUS CoA profiles”With profile_id, Airgate renders a RADIUS CoA enforcement profile:
- The kind comes from the profile’s template:
Disconnectsends a Disconnect-Request,Reauthenticatea reauth,Bounce-Porta bounce,Disable-Porta 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 /coais 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.
CoA log
Section titled “CoA log”GET /coa/log
Section titled “GET /coa/log”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. |
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).
GET /coa/log/counts
Section titled “GET /coa/log/counts”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.
GET /coa/log/{id}
Section titled “GET /coa/log/{id}”Permission: monitor:read
One log entry. 404 when it does not exist in the tenant; 400 for a malformed ID.
Vendor templates
Section titled “Vendor templates”GET /coa/vendors
Section titled “GET /coa/vendors”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 |
Webhook event
Section titled “Webhook event”Every attempt, including failures before transmission, is published as the event coa.sent, which you can receive with a webhook.