Skip to content

Policy administration API

The policy administration API manages a tenant’s policy objects: services (the access policies Airgate selects for each request), roles, role mappings, enforcement policies, enforcement profiles, static host lists (MAC and IP lists) and authentication methods. It backs Access › Access policies, Access › Enforcement profiles and Devices › MAC lists.

The condition syntax, the attribute dictionary, validation and simulation are described in the Access policy API.

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

Objects Read Write
Services, role mappings, enforcement policies, enforcement profiles, authentication methods policy:read policy:write
Roles, static host lists identity:read identity:write

Lists return {"items": [...], "total": N} and accept ?q= (text search), ?limit= (default 50, at most 1000), ?offset= and ?sort= (a field name; prefix - for descending; an unknown field returns 400). Every list also accepts:

  • ?type= to filter by type (matched case-insensitively; an unknown value returns 400);
  • ?system=true|false on objects that have the system flag;
  • ?with_usage=1 to add used_by_count to each item: the number of distinct objects that reference it.

Create returns 201 with the object. Read-only output fields (id, tenant_id, system, created_at, updated_at, hit_count, last_hit_at, entry_count, the *_name(s) output fields) are ignored on input.

PUT is a partial update. Every top-level key in the body replaces that field as a whole (lists and config objects are replaced, not merged). Keys you leave out keep their stored value, so a GET response can be sent back unchanged. Lists of IDs or names in a body take at most 2000 entries.

Names are required, at most 255 characters, without control characters, and unique per tenant and object type regardless of case (409 conflict). description is at most 4096 characters.

System objects ("system": true) are created by Airgate for every tenant. They cannot be deleted or renamed, and the type, method or action that defines them cannot change. Other fields are editable; a system service can be enabled, edited and reordered.

Audit and change events. Every create, update, delete, clone and reorder writes an audit record (object types service, role, role_mapping, enforcement_policy, enforcement_profile, static_host_list, auth_method) and takes effect on the next request.

A validation error names the offending field with its JSON path; a condition error also returns the condition:

{"error": "rules[0].conditions[0] (Tips:Role EQUALS \"[guest]\"): unknown role \"[guest]\" (role names are case-sensitive: did you mean \"[Guest]\"?)",
"code": "bad_request", "field": "rules[0].conditions[0]",
"condition": {"type": "Tips", "name": "Role", "oper": "EQUALS", "value": "[guest]"}}

An unknown ID, or another tenant’s ID, returns 404. Deleting or changing an object that is still referenced returns 409 in_use with the referrers:

{"error": "enforcement profile \"Guest VLAN\" is still referenced", "code": "in_use",
"referrers": [{"type": "enforcement_policy", "id": "cc4c...", "name": "[Sample 802.1X Enforcement]", "where": "rules[3].profile_ids"}]}

Deleting a system object returns 409 with "code": "conflict", "reason": "system".

Services, role mappings and enforcement policies carry condition lists. On every write Airgate runs the same check as POST /policy/validate: at most 200 conditions per list; type and name at most 256 characters and value at most 8192; valid operator, regular expression, CIDR, range and %{...} syntax; device groups and MAC/IP lists named in BELONGS_TO_GROUP must exist; device group names used with value operators on Device:*Group attributes must exist; Tips:Role values must be roles of the tenant or the built-ins [User Authenticated], [Machine Authenticated], Known, Unknown, Disabled. The first problem is returned as 400. A reference to a missing group under a negated operator is always refused, because it would match every request.

POST /services/bulk, /roles/bulk, /enforcement-profiles/bulk and /static-host-lists/bulk take 1 to 500 IDs. Each ID is processed on its own with the same checks as the single request. The response is always 200:

Field Type Meaning
ids array of UUID Objects to act on (duplicates are ignored)
action string Services: enable, disable, monitor, unmonitor, delete. Others: delete.
{"action": "delete", "succeeded": 1, "failed": 1, "results": [
{"id": "...", "name": "Lab Wired", "ok": true, "status": 204},
{"id": "...", "name": "802.1X Wired", "ok": false, "status": 409, "code": "conflict",
"error": "system services cannot be deleted (disable them instead)"}
]}

POST /<objects>/{id}/clone copies an object on the server. The body is optional: {"name": "..."}; the default name is Copy of <name>, then Copy of <name> (2). A requested name that already exists returns 409. A copy is never a system object. A cloned service is disabled and placed at the end of the order. A cloned enforcement profile keeps its encrypted secret values without sending them through the client. Response: 201 with the copy.

A service is an access policy: the conditions that select it for a request, the authentication methods and directories it uses, and the role mapping and enforcement policy that decide the result.

Method Path Permission Purpose
GET /services policy:read List. ?q= searches name, description and template; ?type=, ?enabled=; ?sort= order_no (default), name, type, hit_count, last_hit_at, created_at, updated_at
POST /services policy:write Create
GET /services/{id} policy:read Read
PUT /services/{id} policy:write Update
PATCH /services/{id} policy:write Turn enabled or monitor_mode on or off
DELETE /services/{id} policy:write Delete (204)
POST /services/{id}/clone policy:write Clone
POST /services/bulk policy:write Bulk enable, disable, monitor, unmonitor or delete
PUT /services/order policy:write Set the evaluation order
Field Type Meaning
name string Required
description string
type string RADIUS, TACACS, WEBAUTH or APPLICATION
enabled boolean Default true on create
order_no integer 0 to 1000000; default: end of the list. Enabled services of the request protocol are evaluated by order_no, then name.
monitor_mode boolean Compute and log the decision but always accept
match_type string AND or OR
conditions array Conditions that select the service. An empty list matches every request of the type.
auth_method_ids array of UUID Ordered authentication methods; RADIUS and WEBAUTH only. Empty means any method. Alternative input: auth_method_names.
auth_source_ids array of UUID Ordered directories that authenticate users. Alternative input: auth_source_names.
authz_source_ids array of UUID Additional directories for attribute lookups. Alternative input: authz_source_names.
strip_username array Up to 20 rules {"separator": "@", "keep": "left"} (separator 1 to 4 characters, keep left or right). Alternative input: strip_username_csv, for example "\\:user,user:@".
use_cached_roles boolean
role_mapping_id UUID or null Optional role mapping. Alternative input: role_mapping_name.
enforcement_policy_id UUID Required; an enforcement policy of the same type. Alternative input: enforcement_policy_name.
profiler_enabled boolean Re-evaluate when the device’s type changes
profiler_categories array of string Device categories that trigger it ("ANY" allowed; at most 100)
profiler_coa_profile_id UUID or null A RADIUS_COA enforcement profile to send. Alternative input: profiler_coa_profile_name.
hit_count, last_hit_at Read-only usage counters

The *_names alternatives are used only when the matching ID field is absent, and must match exactly.

Permission: policy:write

Terminal window
curl -s -X POST "$AIRGATE/api/v1/t/$TENANT/services" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"name": "Corp-WiFi", "type": "RADIUS", "match_type": "AND",
"conditions": [{"type": "Radius:IETF", "name": "Called-Station-Id", "oper": "ENDS_WITH", "value": ":Corp-WiFi"}],
"auth_method_names": ["[EAP PEAP]", "[EAP TLS]"],
"auth_source_names": ["[Local User Repository]"],
"enforcement_policy_name": "[Sample 802.1X Enforcement]",
"strip_username_csv": "user:@"}'

Response 201:

{"id": "25b2...", "name": "Corp-WiFi", "type": "RADIUS", "enabled": true, "order_no": 7, "monitor_mode": false,
"match_type": "AND", "conditions": [{"type": "Radius:IETF", "name": "Called-Station-Id", "oper": "ENDS_WITH", "value": ":Corp-WiFi"}],
"auth_method_ids": ["7ea9...", "06f6..."], "auth_method_names": ["[EAP PEAP]", "[EAP TLS]"],
"auth_source_ids": ["8a67..."], "auth_source_names": ["[Local User Repository]"],
"authz_source_ids": [], "authz_source_names": [],
"strip_username": [{"separator": "@", "keep": "left"}],
"role_mapping_id": null, "role_mapping_name": "",
"enforcement_policy_id": "72f3...", "enforcement_policy_name": "[Sample 802.1X Enforcement]",
"hit_count": 0, "last_hit_at": null, "created_at": "2026-10-29T12:47:46Z", "updated_at": "2026-10-29T12:47:46Z"}

Permission: policy:write

Body: {"enabled": true} and/or {"monitor_mode": false}. Any other key returns 400. Response 200 with the service.

Permission: policy:write

Body {"ids": ["...", "..."]}. The listed services get order_no 1 to N in that order; every other service follows in its current order. Unknown or duplicate IDs return 400. Response: the full ordered list in the list envelope.

Permission: policy:write

Returns 204. Returns 409 in_use while a guest portal authenticates through the service, and 409 for a system service.

Method Path Permission Purpose
GET /roles identity:read List. ?q= name and description; ?system=; ?sort= name, created_at, updated_at
POST /roles identity:write Create. Body {"name", "description"}
GET /roles/{id} identity:read Read
PUT /roles/{id} identity:write Update
DELETE /roles/{id} identity:write Delete (204)
POST /roles/bulk identity:write Bulk delete
{"id": "ef1b...", "name": "[Guest]", "description": "Guest users", "system": true, "created_at": "...", "updated_at": "..."}

Policy refers to roles by name. Renaming a role rewrites every role mapping (default_role, rule role) and every Tips:Role condition value that used the old name. A rename is refused (409 in_use) while the guest settings map a role by name; change that mapping first. Deleting a role returns 409 in_use while a role mapping, a condition, a local user, the guest settings, a guest account or a guest portal uses it.

Method Path Permission Purpose
GET /role-mappings policy:read List. ?q=; ?sort= name, created_at, updated_at
POST /role-mappings policy:write Create
GET /role-mappings/{id} policy:read Read
PUT /role-mappings/{id} policy:write Update
DELETE /role-mappings/{id} policy:write Delete (204); 409 while a service uses it
POST /role-mappings/{id}/clone policy:write Clone
Field Type Meaning
name, description string
algorithm string first-applicable (default) or evaluate-all
default_role string Empty (none) or an existing role name
rules array At most 1000. Each: match_type (AND default, or OR), conditions (at least one), role (an existing role name, exact)
{"name": "Corp", "algorithm": "first-applicable", "default_role": "[Other]",
"rules": [{"match_type": "OR", "role": "[Employee]",
"conditions": [{"type": "Authorization:Contoso AD", "name": "memberOf", "oper": "CONTAINS", "value": "Staff"}]}]}
Method Path Permission Purpose
GET /enforcement-policies policy:read List. ?q=, ?type=; ?sort= name, type, created_at, updated_at
POST /enforcement-policies policy:write Create
GET /enforcement-policies/{id} policy:read Read
PUT /enforcement-policies/{id} policy:write Update
DELETE /enforcement-policies/{id} policy:write Delete (204); 409 while a service uses it
POST /enforcement-policies/{id}/clone policy:write Clone
Field Type Meaning
name, description string
type string RADIUS, TACACS, WEBAUTH or APPLICATION. Changing it while a service of another type uses the policy returns 409 in_use.
algorithm string first-applicable (default) or evaluate-all
default_profile_id UUID Required. Alternative input: default_profile_name.
rules array At most 500. Each: match_type, conditions (an empty list matches every request), profile_ids (1 to 50; alternative input profile_names)

Every profile must exist and its type must be allowed for the policy type:

Policy type Allowed profile types
RADIUS RADIUS, RADIUS_COA, POST_AUTH, HTTP, ARUBA_DUR, SESSION, AGENT
TACACS TACACS, POST_AUTH, HTTP, SESSION
WEBAUTH RADIUS_COA, AGENT, HTTP, POST_AUTH, SESSION
APPLICATION APPLICATION, HTTP, POST_AUTH, SESSION
{"name": "Corp Enforcement", "type": "RADIUS", "algorithm": "first-applicable",
"default_profile_name": "[Deny Access Profile]",
"rules": [{"match_type": "AND",
"conditions": [{"type": "Tips", "name": "Role", "oper": "EQUALS", "value": "[Employee]"}],
"profile_names": ["Employee VLAN"]}]}
Method Path Permission Purpose
GET /enforcement-profiles policy:read List. ?q=, ?type=, ?system=; ?sort= name, type, created_at, updated_at
POST /enforcement-profiles policy:write Create
GET /enforcement-profiles/{id} policy:read Read
PUT /enforcement-profiles/{id} policy:write Update
DELETE /enforcement-profiles/{id} policy:write Delete (204); 409 while an enforcement policy or a service uses it
POST /enforcement-profiles/{id}/clone policy:write Clone
POST /enforcement-profiles/bulk policy:write Bulk delete
Field Type Meaning
name, description string
type string RADIUS, RADIUS_COA, TACACS, POST_AUTH, HTTP, AGENT, APPLICATION, ARUBA_DUR or SESSION
action string RADIUS and ARUBA_DUR: ACCEPT, REJECT or DROP. TACACS and APPLICATION: ACCEPT or REJECT. Default ACCEPT; other types ignore it.
attributes array At most 200 {"type", "name", "value"}; values at most 8192 characters and may contain %{...} variables
config object Type-specific settings (below). Changing type without sending config starts from an empty config.
device_group_ids array of UUID Apply the profile only to network devices in one of these device groups. Alternative input: device_group_names.
{"name": "Employee VLAN", "type": "RADIUS", "action": "ACCEPT",
"attributes": [
{"type": "Radius:IETF", "name": "Tunnel-Type", "value": "VLAN (13)"},
{"type": "Radius:IETF", "name": "Tunnel-Medium-Type", "value": "IEEE-802 (6)"},
{"type": "Radius:IETF", "name": "Tunnel-Private-Group-Id", "value": "100"}]}

Attribute values whose name contains password, passphrase, secret or psk, plus MS-MPPE-Send-Key, MS-MPPE-Recv-Key, Aruba-AS-Credential-Hash, NT-Password, LM-Password and every attribute the dictionary marks secret (Tunnel-Password), are encrypted at rest for every profile type. The API returns them as "********", unless the value consists only of %{...} variables. Send "********" back to keep the stored value; a mask without a stored value returns 400. A PUT without attributes keeps the stored list.

RADIUS: attributes with type Radius:<dictionary> (default Radius:IETF) and an attribute name from the dictionary. config is free-form.

ARUBA_DUR (Aruba downloadable user role): config.role_name (default: the profile name), revision or version, attribute (Aruba-CPPM-Role or HP-CPPM-Role), product (Mobility Controller, ArubaOS-Switch, ArubaOS-CX), config_mode (Standard, Advanced), role_definition (the role text, at most 64 KiB).

RADIUS_COA (change of authorization sent after the Access-Accept):

config key Meaning
template Required: Disconnect, Reauthenticate, Bounce-Port, Disable-Port or Custom
kind Read-only, derived from the template: disconnect, reauth, bounce, disable, attributes
packet CoA-Request or Disconnect-Request; derived from the template, only Custom may choose (default CoA-Request)
vendor Optional vendor profile key (for example cisco-iosxe-switch, aruba-aos8, aruba-aoscx, meraki-mr) or auto
delay_sec 0 to 3600 seconds to wait after the Access-Accept

attributes are RADIUS attributes to put in the packet. Custom needs at least one. Empty attributes with vendor: "auto" build the packet from the network device vendor’s template.

TACACS: attributes are AV pairs with type = service (default shell) and name an AV pair name (a trailing * makes it optional); a priv-lvl value must be 0 to 15. config keys: privilege_level (0 to 15), services (list of permitted services), command_authz {"default": "permit"|"deny", "rules": [{"command": "<regex>", "args": "<regex>", "action": "permit"|"deny"}]} (default deny), or the alternative tacacs_command_config {"permit_unmatched_cmds": bool, "commands": [{"command": "..."}]}, and authorize_attribute_status (ADD or REPLACE).

POST_AUTH (update records after the decision): attribute type Endpoint, GuestUser or LocalUser with name = field (an empty value deletes it); Status-Update (name = entity, default Endpoint; value Known, Unknown or Disabled); Expire-Time-Update (name = GuestUser (default), LocalUser or Endpoint); or the session checks Bandwidth-Check, Session-Check, Expiry-Check, Post-Auth-Check, Session-Notify.

HTTP (call an external service after the decision), config is one of:

  • {"context_action_id": "<uuid>"}: a context action defined in the Extensions API;
  • an inline request: url (required, may contain %{...}), method (GET, POST (default), PUT, PATCH, DELETE), headers, body (at most 64 KiB), content_type, ca_cert (PEM), response_attributes ({"<JSON path>": "<device attribute>"});
  • neither, with attributes Target Server and Action (required).

All forms accept context_server_id, timeout_sec (0 to 120), retries (0 to 5) and tls_verify. Credential headers (Authorization, Cookie, names containing token, secret, password, apikey and similar) are returned as "********". Sending the mask back keeps the stored value only while the URL’s host is unchanged.

AGENT, APPLICATION: attributes with a name (at most 128 characters) and a non-empty value. SESSION: config values must be strings, numbers or booleans.

Static host lists are the MAC and IP lists shown on Devices › MAC lists and used by BELONGS_TO_GROUP conditions.

Method Path Permission Purpose
GET /static-host-lists identity:read List. ?q= searches name, description and entries; ?type= MACAddress or IPAddress; ?sort= name, created_at, updated_at; ?summary=1
POST /static-host-lists identity:write Create
GET /static-host-lists/{id} identity:read Read with every entry
PUT /static-host-lists/{id} identity:write Update
DELETE /static-host-lists/{id} identity:write Delete (204); 409 while a condition or a directory uses it
POST /static-host-lists/{id}/clone identity:write Clone
POST /static-host-lists/bulk identity:write Bulk delete
Field Type Meaning
name, description string
host_format string list (default), subnet or regex
host_type string MACAddress (default) or IPAddress
entries array At most 10000: {"value", "description"} objects or plain strings. Duplicates are dropped.

Entries are normalised: a full MAC in any notation becomes aa:bb:cc:dd:ee:ff; a partial MAC (an OUI or prefix) becomes aa:bb:cc; an IP entry may be an address, a CIDR (10.0.0.0/24) or a range (10.0.0.1-10.0.0.50 or 10.0.0.1-50); regex entries are RE2 expressions. An invalid entry returns 400 entries[i].value: ....

With ?summary=1, list items carry entry_count and sample_entries (the first five) instead of entries.

Terminal window
curl -s -X POST "$AIRGATE/api/v1/t/$TENANT/static-host-lists" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"name": "Printers", "host_type": "MACAddress",
"entries": [{"value": "AA-BB-CC-DD-EE-FF", "description": "Floor 2"}, "00:11:22"]}'

Renaming a list rewrites the conditions that refer to it by name. A rename is refused (409 in_use) while a directory of type static host list names it; switch the directory to the list ID first.

Method Path Permission Purpose
GET /auth-methods policy:read List. ?q= name, description and method; ?type=<method>; ?sort= name, method, created_at, updated_at
POST /auth-methods policy:write Create
GET /auth-methods/{id} policy:read Read
PUT /auth-methods/{id} policy:write Update
DELETE /auth-methods/{id} policy:write Delete (204); 409 while a service uses it
POST /auth-methods/{id}/clone policy:write Clone

method is one of PAP, CHAP, MSCHAP, EAP-PEAP, EAP-TLS, EAP-TTLS, EAP-FAST, EAP-GTC, EAP-MD5, EAP-MSCHAPv2, MAC-AUTH, ALLOW-ALL-MAC-AUTH. Unknown config keys are kept; known keys are checked:

config key Values
inner_methods EAP-PEAP: EAP-MSCHAPv2, EAP-GTC, EAP-TLS. EAP-TTLS: PAP, CHAP, MSCHAP, EAP-MSCHAPv2, EAP-GTC, EAP-MD5. EAP-FAST: EAP-MSCHAPv2, EAP-GTC, EAP-TLS.
session_resumption, fast_reconnect, public, authorization_required, anonymous_pac_provisioning, authenticated_pac_provisioning boolean
session_timeout_hours 0 to 168
pac_lifetime_days 1 to 3650
pac_types tunnel, machine, user_auth, posture
cryptobinding none, optional, required
certificate_comparison none, cn_or_san, cn, san, binary
username_from EAP-TLS: Identity, CN, SAN-UPN, SAN-Email, SAN-DNS
ocsp none, optional, required
ocsp_url Empty or an http(s) URL

Permission: policy:read. With only identity:read, the kinds role and static-host-list are allowed and the referrers are returned by name only ("names_only": true). Other kinds return 403.

Lists the objects that refer to an object. kind is service, role, role-mapping, enforcement-policy, enforcement-profile, static-host-list, auth-method, auth-source or nad-group. At most 500 referrers are returned (truncated: true beyond).

{"kind": "role", "id": "ef1b...", "name": "[Guest]", "in_use": true, "truncated": false, "names_only": false,
"referrers": [{"type": "enforcement_policy", "id": "cc4c...", "name": "[Sample 802.1X Enforcement]", "where": "rules[3].conditions[0]"}]}

Referrer type is one of service, role_mapping, enforcement_policy, enforcement_profile, auth_source, local_user, guest_account, guest_portal, guest_settings; where is the field inside the referrer.

Each new tenant gets a set of system objects. Seeded services are disabled until you enable them, so a new tenant authenticates nothing.

Kind Objects
Roles [Guest], [Employee], [Contractor], [Other], [BYOD], [Quarantine], [TACACS Super Admin], [TACACS Read-only Admin], [TACACS Network Admin], [TACACS Help Desk]
Authentication methods [PAP], [CHAP], [MSCHAP], [EAP PEAP], [EAP TLS], [EAP TTLS], [EAP FAST], [EAP MSCHAPv2], [EAP MD5], [EAP GTC], [MAC AUTH], [Allow All MAC AUTH]
RADIUS profiles [Allow Access Profile], [Deny Access Profile], [Drop Access Profile]; editable examples Quarantine VLAN, Guest VLAN, Employee VLAN, Registration VLAN; redirect presets [Aruba Captive Portal Redirect], [Cisco CWA Redirect], [Meraki Splash]
Post-authentication profiles [Update Endpoint Known], [Update Endpoint Unknown], [Update Endpoint Disabled]
CoA profiles [Generic Reauthenticate], [Generic Disconnect], [Cisco - Reauthenticate Session], [Cisco - Bounce-Host-Port], [Cisco - Disable Host-Port], [Cisco - Disconnect], [Aruba Terminate Session], [HPE/Aruba-CX Bounce Port]
TACACS+ profiles [TACACS Deny Profile], [TACACS Super Admin], [TACACS Read-only Admin], [TACACS Network Admin]
Application profiles [Allow Application Access Profile], [Deny Application Access Profile]
Enforcement policies [Allow All Enforcement], [Sample 802.1X Enforcement], [Guest MAC Caching Enforcement], [TACACS Device Admin Enforcement], [Guest Operator Login Enforcement]
Services (disabled) 802.1X Wireless, 802.1X Wired, MAC Authentication, Guest Captive Portal (Web Login), TACACS+ Device Administration, Guest Operator Login

An object you delete is not re-created.

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