Skip to content

Access policy API

The access policy API exposes the policy engine: the attribute dictionary and operators that conditions use, a validator for condition lists, and a simulator that runs a synthetic request through service selection, authentication, role mapping and enforcement. It backs Access › Test access and the condition editors on Access › Access policies and Access › Enforcement profiles.

To create and change the policy objects themselves (services, role mappings, enforcement policies and profiles, authentication methods), use 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 /policy/dictionary policy:read Namespaces, attributes, types, values, operators and groups
GET /policy/operators policy:read Operator catalogue and operators by attribute type
POST /policy/simulate policy:read; policy:write when a password is sent Run the full policy pipeline for a synthetic request
POST /policy/validate policy:read Validate a condition list against the tenant without saving

None of these routes changes configuration. Errors use the standard envelope {"error": "...", "code": "..."} with codes bad_request, not_found, forbidden, rate_limited or internal.

Permission: policy:read

Returns every namespace and attribute a condition, an enforcement profile attribute or a %{...} variable can use.

  • RADIUS dictionaries with attribute type, direction (in, out or inout), a multi-valued flag and enum values written as "Name (N)": Radius:IETF, Radius:Aruba, Radius:Cisco, Radius:Hewlett-Packard-Enterprise, Radius:Hewlett-Packard-Enterprise-2, Radius:H3C, Radius:Extreme, Radius:Brocade, Radius:Alcatel-Lucent-Enterprise, Radius:Airespace, Radius:Microsoft, Radius:Juniper, Radius:Fortinet, Radius:Ruckus, Radius:Arista, Radius:Meraki and Radius:Tellabs. Where the RADIUS server spells an attribute differently, freeradius_name gives the name actually sent (for example HPE-User-Role is sent as HP-User-Role). Rules and profiles accept either name.
  • Fixed namespaces: Connection, Authentication, Endpoint, Device, Tips, Date, Certificate, GuestUser, LocalUser, TACACS, Host, Application and Onboard.
  • Tenant-specific values: Tips:Role lists the tenant’s roles plus [User Authenticated] and [Machine Authenticated]; Device:Device-Group lists the device group names; Authentication:Source lists the directory names. Custom attributes found on devices, network devices and local users are added with "custom": true. Each directory gets an Authorization:<directory name> namespace with its attribute aliases.
  • Secret attributes carry "secret": true (for example Tunnel-Password). Their values in enforcement profiles are encrypted at rest and masked by the API.
  • Pseudo attributes carry "pseudo": true and a description. Airgate turns them into real reply attributes. Today: Cisco-IP-Downloadable-ACL in Radius:Cisco, where each ACE line becomes Cisco-AVPair += "ip:inacl#N=<ace>".
  • operators, operators_by_type (guidance for editors; the engine accepts any operator on any attribute), groups (device groups and MAC/IP lists), the tenant timezone and the supported variables forms.

Attribute types: string, integer, enum, ipaddr, ipv6addr, mac, datetime, date, time (time of day), day, boolean, list, version, octets.

Terminal window
curl -s "$AIRGATE/api/v1/t/$TENANT/policy/dictionary" \
-H "Authorization: Bearer $TOKEN"
{
"namespaces": [
{"name": "Radius:IETF", "attributes": [
{"name": "NAS-Port-Type", "type": "enum", "values": ["Ethernet (15)", "Wireless-802.11 (19)"], "direction": "in"},
{"name": "Reply-Message", "type": "string", "multi_valued": true, "direction": "out"}
]},
{"name": "Tips", "attributes": [
{"name": "Role", "type": "list", "values": ["[User Authenticated]", "[Machine Authenticated]", "[Employee]", "[Guest]"]}
]}
],
"operators": [{"name": "EQUALS", "arity": "scalar", "negated": false, "description": "any value equals"}],
"operators_by_type": {"ipaddr": ["IN_SUBNET", "BELONGS_TO_GROUP"]},
"groups": {"nad_groups": ["Branch Switches"], "static_host_lists": ["Printers"]},
"timezone": "UTC",
"variables": ["%{Namespace:Attribute}", "%{Radius:<Vendor>:<Attribute>}", "%{Authorization:<source name>:<alias>}"]
}

Permission: policy:read

Returns the operator catalogue (name, arity, negated, description) and operators_by_type.

{"operators": [{"name": "IN_RANGE", "arity": "range", "negated": false, "description": "low <= value <= high (times of day may wrap midnight)"}],
"operators_by_type": {"integer": ["EQUALS", "NOT_EQUALS", "BELONGS_TO"]}}

A condition has the form {"type": "<namespace>", "name": "<attribute>", "oper": "<operator>", "value": "<value>"}. A list of conditions is combined with a match_type of AND or OR. An empty list is true.

Operator True when (the attribute may have several values)
EQUALS / NOT_EQUALS any value equals / the attribute is present and no value equals
EQUALS_IGNORE_CASE / NOT_EQUALS_IGNORE_CASE the same, ignoring case
CONTAINS / NOT_CONTAINS the configured string is a substring of a value
BEGINS_WITH / NOT_BEGINS_WITH, ENDS_WITH / NOT_ENDS_WITH prefix / suffix
EXISTS / NOT_EXISTS present and not empty / absent (the value is ignored)
BELONGS_TO / NOT_BELONGS_TO a value is in the list / the attribute is present and no value is
MATCHES_ANY / NOT_MATCHES_ANY the attribute’s values and the list intersect / are disjoint
MATCHES_ALL / NOT_MATCHES_ALL every list item is among the attribute’s values / not
MATCHES_EXACT / NOT_MATCHES_EXACT the two sets are equal / differ
BELONGS_TO_GROUP / NOT_BELONGS_TO_GROUP the value is in a device group or a MAC/IP list (see below)
MATCHES_REGEX / NOT_MATCHES_REGEX RE2 regular expression, unanchored
LESS_THAN, LESS_THAN_OR_EQUALS, GREATER_THAN, GREATER_THAN_OR_EQUALS typed comparison
IN_RANGE / NOT_IN_RANGE inclusive range low,high, low..high or low - high; times of day may wrap midnight (22:00,06:00)
IN_SUBNET / NOT_IN_SUBNET IP address inside any of the comma-separated CIDRs or addresses

Rules that apply to every operator:

  • When the attribute is absent, every operator is false except NOT_EXISTS, including the other NOT_* operators.
  • Operator names are case-insensitive.
  • A value of exactly %{X} is replaced by the values of X. When a reference cannot be resolved, the condition is false.
  • List values are split on <br> when present, otherwise on ,.
  • Enum values compare by name (case-insensitive) or by code. MAC addresses compare in any notation; IP addresses, numbers, dates and versions compare by type (10.1 is not equal to 10.10 for a version attribute).

Groups. For BELONGS_TO_GROUP, attributes that describe the network device (Connection:NAD-*, Device:*, NAS-IP-Address, NAS-IPv6-Address, NAS-Identifier) refer to a device group first; every other attribute refers to a MAC/IP list (static host list) first. The value is a group name, a group ID, or a name with a prefix that forces the kind: HostList:, StaticHostList:, SHL: for a list; NadGroup:, DeviceGroup:, NDG: for a device group.

Date namespace. Computed in the tenant time zone when the request does not carry it: Day-of-Week, Time-of-Day (HH:MM:SS), Date-of-Year (YYYY-MM-DD), Day-of-Month, Month, Year, Date-Time (YYYY-MM-DD HH:MM:SS).

Permission: policy:read

Checks a condition list against the tenant’s current policy without saving it: operator, attribute, regular expression, CIDR, range, list and %{...} syntax; that referenced device groups and MAC/IP lists exist; and that Tips:Role names used with value operators exist. Role and group names are case-sensitive except under the *_IGNORE_CASE operators; a case-only mismatch is reported with a hint. This is the same check the policy administration API runs on every write.

Field Type Meaning
match_type string AND or OR
conditions array Conditions to check, at most 1000
Terminal window
curl -s -X POST "$AIRGATE/api/v1/t/$TENANT/policy/validate" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"match_type": "OR", "conditions": [
{"type": "Connection", "name": "Client-Mac-Address", "oper": "BELONGS_TO_GROUP", "value": "Nope"},
{"type": "Host", "name": "Name", "oper": "MATCHES_REGEX", "value": "("}]}'

Response 200:

{"valid": false, "issues": [
{"index": 0, "field": "value", "code": "unknown_group", "message": "unknown NAD group / static host list \"Nope\""},
{"index": 1, "field": "condition", "code": "syntax", "message": "invalid regular expression: ..."}
]}

index is the condition’s position (-1 for an invalid match_type). code is one of syntax, template, match_type, unknown_group, unknown_nad_group, unknown_role. fail_open: true is present on unknown-object issues under a negated operator.

Permission: policy:read. With a password, policy:write.

Runs a synthetic request through service selection, username stripping, identity lookup or password verification, device and guest attribute lookup, role mapping and enforcement. It has no side effects: no service hit counters, device updates, CoA, sign-in records or events.

Field Type Meaning
protocol string RADIUS (default), TACACS, WEBAUTH or APPLICATION. Any other value returns 400.
service_id UUID Force this service instead of running service selection. 404 if it is not the tenant’s.
nad_id UUID Network device of the tenant (404 otherwise).
nad_ip string Network device IP address. When it matches one of the tenant’s devices, the Device:* attributes are filled. An invalid address returns 400.
username string User name. When absent, taken from Radius:IETF:User-Name or TACACS:UserName.
password string Verify this password against the service’s directories instead of only looking the user up.
mac string Client MAC address. Fills Connection:Client-Mac-Address and its variants, and Calling-Station-Id for RADIUS. An invalid value returns 400.
skip_identity boolean Do not look the user up at all; evaluate only the attributes you supply.
attributes object {"<namespace>": {"<attribute>": value or [values]}}. Supplied attributes win over derived ones. Date:Date-Time simulates a point in time.
Terminal window
curl -s -X POST "$AIRGATE/api/v1/t/$TENANT/policy/simulate" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"protocol": "RADIUS", "nad_ip": "10.0.0.4", "username": "alice@contoso.com",
"mac": "02-00-00-00-00-05",
"attributes": {"Radius:IETF": {"NAS-Port-Type": "Wireless-802.11"}}}'

Response 200:

{
"service": {"id": "6f7c...", "name": "Corp-WiFi", "type": "RADIUS"},
"authentication": {"performed": true, "verified": false, "result": "ok", "username": "alice", "source": "Contoso AD"},
"decision": {
"result": "ACCEPT", "reason": "", "service_name": "Corp-WiFi", "monitor_mode": false,
"auth_source": "Contoso AD", "roles": ["[Employee]", "[User Authenticated]"],
"enforcement_policy": "Corp Enforcement", "profiles": ["Employee VLAN"],
"radius_reply": [{"name": "Tunnel-Private-Group-Id", "op": ":=", "value": "20"}],
"trace": ["Service \"Corp-WiFi\" (order 10, AND): matched", "...", "Result: ACCEPT"]
},
"context": {"Authentication": {"Username": ["alice"]}, "Tips": {"Role": ["[Employee]", "[User Authenticated]"]}}
}
  • authentication.result is ok, failed or skipped. When authentication fails, error is set, decision.result is REJECT with reason authentication failed: ..., and enforcement does not run.
  • When no service matches, service is null and decision.result is REJECT with reason no service matched (still 200).
  • Secret values (for example Tunnel-Password or a Wi-Fi passphrase) are returned as "********" everywhere in the decision and the context.

The simulator returns the same decision the RADIUS and TACACS+ services use:

  1. Identity roles: roles from the user or guest account, from directory lookups, the device status (Known, Unknown, Disabled), and the built-in roles [User Authenticated] and [Machine Authenticated].
  2. Role mapping (optional, set on the service): first-applicable uses the first matching rule’s role, evaluate-all uses every matching rule’s role; when nothing matches, the default role. The result is written to Tips:Role.
  3. Enforcement policy: first-applicable applies the first matching rule’s profiles, evaluate-all the union of every matching rule’s profiles; when nothing matches, the default profile. A missing policy, no match without a default profile, or a rule with no profiles is a REJECT.
  4. Device-group filter: a profile limited to device groups applies only when the network device is in one of them.
  5. Merge: DROP beats REJECT beats ACCEPT. Single-valued RADIUS attributes are first-wins; multi-valued ones (Cisco-AVPair, Reply-Message, Framed-Route, any *-AVPair) are appended. An Access-Reject carries only Reply-Message.
  6. Monitor mode (set on the service): the decision is computed and traced, but the result is ACCEPT with reason monitor mode (enforcement result X: ...) and no reply attributes are sent.

An enforcement profile whose encrypted secret value cannot be decrypted is unusable: any decision that selects it is a REJECT with reason enforcement profile "<name>" is unusable: a sealed secret value cannot be decrypted.

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