TACACS+ device administration API
Airgate’s TACACS+ server (RFC 8907) authenticates administrators who sign in to switches, routers, firewalls and controllers, authorizes their exec sessions and commands, and stores accounting. This API configures the service per tenant and exposes its cached login decisions, accounting log and counters. It backs Monitor › Admin login log; the TACACS+ access policies themselves are services of type TACACS in the Policy administration API.
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.
| Method | Path | Permission | Purpose |
|---|---|---|---|
GET |
/tacacs/settings |
policy:read |
Tenant TACACS+ settings |
PUT |
/tacacs/settings |
policy:write |
Update settings (partial) |
GET |
/tacacs/service-dictionary |
policy:read |
TACACS+ services and their attributes |
POST |
/tacacs/service-dictionary |
policy:write |
Create a custom service |
POST |
/tacacs/service-dictionary/import |
policy:write |
Import service dictionary XML |
GET |
/tacacs/service-dictionary/{id} |
policy:read |
Read a service |
PUT |
/tacacs/service-dictionary/{id} |
policy:write |
Update a custom service |
DELETE |
/tacacs/service-dictionary/{id} |
policy:write |
Delete a custom service |
GET |
/tacacs/sessions |
monitor:read |
Cached login decisions |
GET |
/tacacs/sessions/{id} |
monitor:read |
One cached decision |
DELETE |
/tacacs/sessions/{id} |
monitor:coa |
Revoke one cached decision |
POST |
/tacacs/sessions/clear |
monitor:coa |
Revoke cached decisions of a user, a device or all |
GET |
/tacacs/accounting |
monitor:read |
Accounting log (commands, exec sessions) |
GET |
/tacacs/accounting/{id} |
monitor:read |
One accounting record |
GET |
/tacacs/status |
monitor:read |
Listener state and per-device counters |
POST |
/tacacs/simulate |
policy:read; policy:write with a password |
Simulate a login, authorization and command check |
Errors use the standard envelope with codes bad_request, not_found, forbidden, conflict or internal.
How TACACS+ requests are handled
Section titled “How TACACS+ requests are handled”- Which device. Airgate identifies the network device by the connection’s source address and uses its TACACS+ shared secret. Connections from an unknown or disabled device, a device without a TACACS+ secret, or a tenant with TACACS+ disabled are dropped without a reply. Devices at a site can also reach Airgate through a site connector.
- Service selection. Airgate selects the first enabled service of type
TACACSwhose conditions match. A new tenant has the seededTACACS+ Device Administrationservice, which is disabled: until you enable it or your own TACACS+ service, every request fails withno TACACS+ service matched. - Authentication. ASCII, PAP and CHAP are supported (CHAP needs a reversible password). An unreachable directory returns ERROR, so the device fails over as for an unreachable server.
- Login cache. A successful login stores the decision for the device, device address, user and remote address for
session_cache_minutes(default 12 hours). Exec and command authorization requests use it. Without a cached login and withauthorize_without_loginon, Airgate evaluates the policy without a password (for SSH keys or device-local logins). - Privilege level and commands. The enforcement profiles set the privilege level, the permitted services and AV pairs, and command rules. Command rules are case-insensitive RE2 regular expressions; the first matching rule wins, otherwise the profile’s default (
permitordeny). Withenforce_privilege_cap, an ENABLE or command level above the decision’s level is refused. - Accounting. Each record is stored before Airgate replies SUCCESS; a storage failure replies ERROR so the device can retry another server.
Sign-in records appear on Monitor › Sign-in log and Monitor › Admin login log.
Settings
Section titled “Settings”GET /tacacs/settings
Section titled “GET /tacacs/settings”Permission: policy:read
Defaults are returned, with updated_at: null, until the first update.
{"enabled": true, "single_connect": true, "session_cache_minutes": 720, "authorize_without_login": true, "enforce_privilege_cap": true, "record_authorizations": true, "accounting_retention_days": 90, "updated_at": "2026-10-29T10:00:00Z"}| Field | Type | Meaning |
|---|---|---|
enabled |
boolean | false drops connections from this tenant’s devices |
single_connect |
boolean | Honour the TACACS+ single-connect flag |
session_cache_minutes |
integer | Login cache lifetime, 1 to 10080 |
authorize_without_login |
boolean | Without a cached login, evaluate policy without a password |
enforce_privilege_cap |
boolean | ENABLE level and command priv_lvl may not exceed the decision’s level |
record_authorizations |
boolean | Write every authorization request to the sign-in log |
accounting_retention_days |
integer | Delete accounting records older than this, 1 to 3650 |
PUT /tacacs/settings
Section titled “PUT /tacacs/settings”Permission: policy:write
Partial update: absent fields keep their value. Returns 200 with the full settings; 400 for out-of-range numbers. Audited.
curl -s -X PUT "$AIRGATE/api/v1/t/$TENANT/tacacs/settings" \ -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \ -d '{"session_cache_minutes": 480, "record_authorizations": false}'Service dictionary
Section titled “Service dictionary”The service dictionary lists the TACACS+ services and attribute names that TACACS+ enforcement profiles offer. Built-in services (system: true, read-only) are Shell, PIX Shell, PPP:IP, PPP:IPX, PPP:LCP, ARAP, CiscoWLC:Common, Wireless-WCS:HTTP, Aruba:Common, AMP:https, junos-exec, fortigate and paloalto. Custom services belong to the tenant.
{"id": "0b5c...", "name": "Acme:Mgmt", "service": "Acme", "protocol": "Mgmt", "description": "Acme appliances", "system": false, "attributes": [{"name": "role", "type": "Enum", "values": ["admin", "viewer"]}, {"name": "level", "type": "Integer", "values": []}], "created_at": "...", "updated_at": "..."}name is service[:protocol] and is used as the attribute type in TACACS+ profiles; service and protocol are derived from it. Attribute type is String, Integer, Boolean, Enum (needs values), IPAddress or List.
GET /tacacs/service-dictionary
Section titled “GET /tacacs/service-dictionary”Permission: policy:read
Query q (name or description), system (true for built-ins only, false for custom only), limit, offset. Sorted by name.
GET /tacacs/service-dictionary/{id}
Section titled “GET /tacacs/service-dictionary/{id}”Permission: policy:read
A built-in or custom service; 404 otherwise.
POST /tacacs/service-dictionary
Section titled “POST /tacacs/service-dictionary”Permission: policy:write
| Field | Type | Meaning |
|---|---|---|
name |
string | Required, at most 64 characters, at most one :, no =, * or control characters, not a built-in name |
description |
string | |
attributes |
array | {"name", "type", "values"}. Names unique (case-insensitive), without =, * or whitespace. |
curl -s -X POST "$AIRGATE/api/v1/t/$TENANT/tacacs/service-dictionary" \ -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \ -d '{"name": "Acme:Mgmt", "description": "Acme appliances", "attributes": [{"name": "role", "type": "Enum", "values": ["admin", "viewer"]}]}'Returns 201 with the service; 400 for a validation error; 409 when the name exists.
PUT /tacacs/service-dictionary/{id}
Section titled “PUT /tacacs/service-dictionary/{id}”Permission: policy:write
Same body and validation. Returns 200. Built-in services return 400.
DELETE /tacacs/service-dictionary/{id}
Section titled “DELETE /tacacs/service-dictionary/{id}”Permission: policy:write
Returns 204. Built-in services return 400.
POST /tacacs/service-dictionary/import
Section titled “POST /tacacs/service-dictionary/import”Permission: policy:write
Body: service dictionary XML (Content-Type: application/xml or text/xml), or JSON {"xml": "..."}. Every <TacacsServiceDictionary name=".." [dispName=".."]> element with <ServiceAttribute name=".." dataType=".." [allowedValues="a,b"]/> children is created or updated by name in one transaction. Unknown data types become String.
<TacacsServiceDictionaries> <TacacsServiceDictionary dispName="fortigate2" name="fortigate2"> <ServiceAttribute dataType="String" dispName="memberof" name="memberof"/> </TacacsServiceDictionary></TacacsServiceDictionaries>{"created": 1, "updated": 0, "skipped": [{"name": "Shell", "reason": "built-in service"}], "items": [{"id": "...", "name": "fortigate2", "service": "fortigate2", "protocol": "", "system": false, "attributes": [{"name": "memberof", "type": "String", "values": []}]}]}400 for invalid XML or XML without dictionary elements.
Cached logins
Section titled “Cached logins”GET /tacacs/sessions
Section titled “GET /tacacs/sessions”Permission: monitor:read
| Query | Meaning |
|---|---|
username |
Exact user name, case-insensitive |
nad_id |
Network device ID |
origin |
login or authorization |
q |
Search user name, remote address, device address, device name, service name |
include_expired |
true to include expired entries |
limit, offset |
Paging |
Newest first. Secret AV pair values are returned as "********".
{"items": [{ "id": "8c1e...", "nad_id": "41d0...", "nad_name": "core-sw1", "nad_ip": "10.0.0.2", "username": "alice", "rem_addr": "10.0.0.50", "port": "vty1", "auth_username": "alice", "service_id": "5a7b...", "service_name": "TACACS Device Admin", "auth_source": "[Local User Repository]", "roles": ["NetAdmin", "[User Authenticated]"], "profiles": ["[TACACS Super Admin]"], "priv_level": 15, "monitor_mode": false, "replace_args": false, "tacacs": {"priv_level": 15, "services": {"Shell": []}, "commands": {"default": "deny", "rules": [{"command": "^show$", "args": "", "action": "permit"}]}}, "origin": "login", "created_at": "...", "refreshed_at": "...", "expires_at": "...", "active": true}], "total": 1}tacacs is null when the decision had no TACACS+ profile; commands is omitted when no profile restricts commands. nad_ip is the address of the device the login came from.
GET /tacacs/sessions/{id}
Section titled “GET /tacacs/sessions/{id}”Permission: monitor:read
One entry, expired ones included; 404 otherwise.
DELETE /tacacs/sessions/{id}
Section titled “DELETE /tacacs/sessions/{id}”Permission: monitor:coa
Returns 204. The user’s next authorization request on that device is evaluated again (or refused when authorize_without_login is off). Other service instances may answer from their short-lived local copy for up to 15 seconds. Audited (revoke).
POST /tacacs/sessions/clear
Section titled “POST /tacacs/sessions/clear”Permission: monitor:coa
| Field | Type | Meaning |
|---|---|---|
username |
string | Revoke this user’s entries |
nad_id |
UUID or null | Revoke the entries of this network device |
all |
boolean | Revoke every entry of the tenant |
At least one is required (400 otherwise). Returns 200 {"deleted": 2}. Audited.
Accounting
Section titled “Accounting”GET /tacacs/accounting
Section titled “GET /tacacs/accounting”Permission: monitor:read
| Query | Meaning |
|---|---|
from, to |
RFC 3339 or YYYY-MM-DD; from inclusive, to exclusive |
username |
Exact user name, case-insensitive |
nad_id |
Network device ID |
flags |
START, STOP, WATCHDOG or START|WATCHDOG (URL-encode the | as %7C) |
task_id |
Task ID |
command |
Substring of the command |
q |
Search user name, command, remote address, device name or address |
limit, offset |
Paging |
curl -s "$AIRGATE/api/v1/t/$TENANT/tacacs/accounting?username=alice&from=2026-10-29" \ -H "Authorization: Bearer $TOKEN"{"items": [{ "id": "c0a8...", "at": "2026-10-29T09:05:12Z", "nad_id": "41d0...", "nad_name": "core-sw1", "nad_ip": "10.0.0.2", "username": "alice", "port": "vty3", "rem_addr": "10.0.0.50", "flags": "STOP", "task_id": "12", "service": "shell", "protocol": "", "priv_lvl": 15, "authen_method": "TACACSPLUS", "authen_type": "ASCII", "authen_service": "LOGIN", "command": "show interfaces Ethernet1", "elapsed_seconds": null, "args": ["task_id=12", "service=shell", "priv-lvl=15", "cmd=show interfaces Ethernet1 <cr>"]}], "total": 1}command is empty for exec START, STOP and WATCHDOG records. 400 for an invalid from, to, nad_id or flags.
GET /tacacs/accounting/{id}
Section titled “GET /tacacs/accounting/{id}”Permission: monitor:read
One record; 404 otherwise.
Status
Section titled “Status”GET /tacacs/status
Section titled “GET /tacacs/status”Permission: monitor:read
The listener state of the service instance that answers, the tenant’s active cached logins, and that instance’s counters (since it started) for the tenant’s devices that have connected.
{"listening": true, "addr": "[::]:49", "started_at": "...", "last_error": "", "enabled": true, "proxy_protocol": false, "active_logins": 12, "totals": {"connections_open": 2, "connections": 40, "authen_pass": 30, "authen_fail": 2, "authen_error": 0, "author_pass": 900, "author_fail": 5, "author_error": 0, "acct": 910, "acct_error": 0, "bad_packets": 0}, "nads": [{"nad_id": "41d0...", "nad_name": "core-sw1", "nad_ip": "10.0.0.2", "connections_open": 2, "bad_packets": 0, "last_seen": "...", "last_bad_packet_at": null, "last_bad_packet": ""}]}Simulation
Section titled “Simulation”POST /tacacs/simulate
Section titled “POST /tacacs/simulate”Permission: policy:read. With a password, policy:write.
Runs the login, authorization and command check for a synthetic request. Nothing is cached, recorded or changed.
| Field | Type | Meaning |
|---|---|---|
username |
string | Required |
password |
string | Verify the password. Without it, the request is evaluated in authorization-only mode. |
nad_id / nad_ip |
UUID / string | The network device (nad_id must be the tenant’s, 404 otherwise). An address that is not one of the tenant’s devices is simulated without Device:* attributes. |
authen_type |
string | ASCII (default), PAP or CHAP |
authen_service |
string | LOGIN (default) or ENABLE |
priv_lvl |
integer | 0 to 15; default 15 for ENABLE, otherwise 1 |
port, rem_addr |
string | Terminal port and remote address |
service, protocol |
string | Requested service (default shell) and protocol |
command |
string | Command line to authorize (optional) |
command_priv_lvl |
integer | 0 to 15; default: the decision’s level when set, otherwise priv_lvl |
curl -s -X POST "$AIRGATE/api/v1/t/$TENANT/tacacs/simulate" \ -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \ -d '{"nad_ip": "10.0.0.2", "username": "bob", "command": "show running-config"}'{"nad": {"id": "41d0...", "name": "core-sw1", "ip": "10.0.0.2", "vendor": "Arista"}, "authentication": {"mode": "authorization_only", "result": "ACCEPT", "reason": "", "error_code": 0, "username": "bob", "auth_source": "[Local User Repository]"}, "decision": {"result": "ACCEPT", "service_name": "TACACS Device Admin", "roles": ["Helpdesk", "[User Authenticated]"], "profiles": ["Shell Helpdesk"], "trace": ["..."]}, "authorization": {"service": "shell", "protocol": "", "status": "PASS_ADD", "args": ["priv-lvl=1"], "services": ["Shell"], "reason": ""}, "command": {"line": "show running-config", "priv_lvl": 1, "status": "FAIL", "permit": false, "rule": 1, "reason": "rule 1 (deny \"^show$\" args \"^running-config\")"}, "context": {"Connection": {"Protocol": ["TACACS+"]}}, "trace": ["..."]}authorization and command are null unless authentication resulted in ACCEPT; command is also null without a command. Secret values are returned as "********". nad is null when no device was given.