Skip to content

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.

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.

  • 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 TACACS whose conditions match. A new tenant has the seeded TACACS+ Device Administration service, which is disabled: until you enable it or your own TACACS+ service, every request fails with no 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 with authorize_without_login on, 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 (permit or deny). With enforce_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.

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

Permission: policy:write

Partial update: absent fields keep their value. Returns 200 with the full settings; 400 for out-of-range numbers. Audited.

Terminal window
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}'

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.

Permission: policy:read

Query q (name or description), system (true for built-ins only, false for custom only), limit, offset. Sorted by name.

Permission: policy:read

A built-in or custom service; 404 otherwise.

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

Permission: policy:write

Same body and validation. Returns 200. Built-in services return 400.

Permission: policy:write

Returns 204. Built-in services return 400.

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.

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.

Permission: monitor:read

One entry, expired ones included; 404 otherwise.

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

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.

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

Permission: monitor:read

One record; 404 otherwise.

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": ""}]}

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

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