Skip to content

BYOD API

The BYOD API manages self-service onboarding portals and the devices users onboard through them. It backs BYOD › BYOD portals and BYOD › BYOD devices in the console, and it describes the public portal endpoints and the AirEnroll enrollment contract that devices call.

  • Admin routes are relative to /api/v1/t/{tenant}, where {tenant} is the tenant slug or ID. They need a bearer token; see API overview for authentication.
  • Reading needs onboard:read; changing portals and revoking devices needs onboard:write.
  • Public portal routes live under /byod/{tenant}/{portal} from the root of your Airgate address. They use the portal’s own sign-in, not an API token. A disabled tenant or portal answers 404.

Every admin change is written to the audit log (object type byod_portal for create, update and delete; byod_device for revoke).

Permission: onboard:read

Lists the tenant’s BYOD portals.

Response 200: {"items": [Portal], "total": N}. Each portal also carries the read-only fields public_url, redirect_uri, default_server_names, active_devices, and signin.source_name / signin.source_type.

Terminal window
curl -s "$AIRGATE/api/v1/t/$TENANT/byod-portals" \
-H "Authorization: Bearer $TOKEN"

Permission: onboard:write

Creates a portal. Fields you leave out take their defaults (enabled, Microsoft sign-in, 3 devices per user, 365-day certificates, every platform).

Field Type Meaning
slug string Part of the portal address. 1–63 lower-case letters, digits and hyphens. Required.
name string Display name, at most 100 characters. Required.
description string Free text.
enabled boolean Default true.
signin.mode string entra_oidc (Microsoft sign-in) or password.
signin.source_id UUID The directory users sign in with. entra_oidc needs a Microsoft Entra ID directory. Guest, endpoint, MAC list, time and device-type sources are refused. Required.
allowed_groups string[] When set, only members of one of these groups (names or IDs, case-insensitive) may onboard. At most 50.
max_devices_per_user integer 1–100. Default 3.
cert_validity_days integer 1–1825. Default 365.
target_ssid string The Wi-Fi network devices are set up for, 1–32 bytes. Required.
server_name string RADIUS server name devices validate. A DNS name, or empty to use the names of the tenant’s EAP server certificate.
platforms string[] Any of apple, windows, android, chromeos, linux, other. At least one.
require_terms boolean Users must accept terms before signing in.
terms string At most 20 000 characters. Required when require_terms is true.
branding.title, branding.heading, branding.message, branding.footer string Page text (at most 100, 200, 2000 and 1000 characters).
branding.logo string Image data URI (PNG, JPEG, GIF, WebP or SVG), at most 256 KB.
branding.primary_color, branding.background_color, branding.text_color string #rgb or #rrggbb.
Terminal window
curl -s -X POST "$AIRGATE/api/v1/t/$TENANT/byod-portals" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"slug":"staff","name":"Staff devices",
"signin":{"mode":"entra_oidc","source_id":"6f1c2a9e-0d4b-4c51-9a77-1f0e2b3c4d5e"},
"allowed_groups":["Wi-Fi BYOD"],"target_ssid":"Corp-WiFi",
"platforms":["apple","windows","android"]}'

Response 201: the portal.

{
"id": "0b7e…", "slug": "staff", "name": "Staff devices", "enabled": true,
"signin": {"mode": "entra_oidc", "source_id": "6f1c…", "source_name": "Contoso Entra ID", "source_type": "EntraID"},
"allowed_groups": ["Wi-Fi BYOD"], "max_devices_per_user": 3, "cert_validity_days": 365,
"target_ssid": "Corp-WiFi", "server_name": "", "platforms": ["apple", "windows", "android"],
"require_terms": false, "terms": "",
"branding": {"title": "Connect your device", "heading": "Connect your device to Wi-Fi", "message": "…"},
"public_url": "https://airgate.contoso.com/byod/contoso/staff",
"redirect_uri": "https://airgate.contoso.com/byod/contoso/staff/callback",
"default_server_names": ["radius.contoso.com"], "active_devices": 0
}

A slug already in use answers 409 conflict; a validation failure answers 400 bad_request with the reason.

Permission: onboard:read

Returns one portal. Unknown ID: 404.

Permission: onboard:write

Partial update: fields you leave out keep their current values. Same fields and validation as create. Changing the sign-in settings or the slug, or disabling the portal, ends every open portal session, so signed-in visitors start again. Response 200: the portal.

Permission: onboard:write

Deletes the portal. Devices and their certificates stay; they lose the link to the portal. Response 204.

Permission: onboard:read

Returns the portal’s landing page as HTML with sign-in disabled. Works for disabled portals too.

Permission: onboard:read

Query Type Meaning
owner string Only this owner’s devices.
status string active or revoked. Anything else answers 400.
q string Matches owner, name, MAC, certificate serial and model.
limit, offset integer Paging. Default limit 50, at most 1000.

Response 200: {"items": [Device], "total": N}.

Terminal window
curl -s "$AIRGATE/api/v1/t/$TENANT/byod-devices?owner=alice@contoso.com&status=active" \
-H "Authorization: Bearer $TOKEN"
{"items": [{
"id": "5c2d…", "portal_id": "0b7e…", "portal_name": "Staff devices",
"owner": "alice@contoso.com", "display_name": "Alice's iPhone", "platform": "apple",
"os_version": "17.5", "model": "iPhone", "user_agent": "…", "mac": "3c:22:fb:12:34:56",
"cert_id": "9a1e…", "cert_serial": "4f9c…", "cert_not_after": "2027-11-19T10:00:00Z",
"status": "active", "created_at": "2026-11-19T10:00:00Z", "last_seen_at": "2026-11-19T10:02:11Z",
"revoked_at": null, "revoked_by": ""
}], "total": 1}

status is pending (being set up), active or revoked.

Permission: onboard:read

Returns one device. Unknown ID: 404.

Permission: onboard:write

Revokes the device certificate (the CRL and OCSP answer change at once), sends a CoA Disconnect for the device’s last MAC address, sets the endpoint attribute BYOD to false and marks the device revoked. Response 200: the device. A device that is already revoked, or still being set up, answers 409 conflict.

Terminal window
curl -s -X POST "$AIRGATE/api/v1/t/$TENANT/byod-devices/5c2d…/revoke" \
-H "Authorization: Bearer $TOKEN"

Permission: onboard:read

{"active": 42, "revoked": 3, "users": 30, "onboarded_last_7_days": 6,
"seen_last_24h": 35, "portals": 2, "by_platform": {"apple": 20, "windows": 15, "android": 7}}

These routes serve the pages users see. They are listed so you can allow them through proxies and firewalls and understand the flow; they are not meant for scripts. All paths are under /byod/{tenant}/{portal}.

Method Path What it does
GET / Landing page with sign-in and, when required, the terms. A captive-portal mac= or client_mac= query is carried along.
POST /login Username and password sign-in (password mode).
GET /login/entra Starts Microsoft sign-in (authorization code with PKCE).
GET /callback Microsoft sign-in redirect URI.
GET /device Choose the platform and name the device. ?platform= preselects a platform.
POST /issue Issues the device certificate and shows the install steps, or the AirEnroll page.
GET /download?t= One-time download of the Wi-Fi profile or certificate bundle: single use, valid 10 minutes. Used or expired: 410; unknown: 404.
GET /done?d= Waits until Airgate’s RADIUS service has seen the device, then shows Done.
GET /devices My devices: the signed-in user’s devices.
POST /devices/{id}/remove The user removes (revokes) one of their devices.
POST /logout Ends the portal session.
GET /ca.crt Root CA (DER) of the RADIUS server certificate chain, for manual installs.
GET /apps/android The AirEnroll Android app (airenroll.apk). 404 when it is not available or Android is not offered.
GET /apps/windows?t=<token>[&arch=arm64] The AirEnroll Windows agent, saved as AirEnroll-<token>.exe.
GET /apps/version Versions of the AirEnroll files available (JSON).
GET /app/enroll?t=<token> The AirEnroll enrollment (JSON).

Portal sessions last 30 minutes and use an HttpOnly cookie scoped to the portal path. Every form post checks a CSRF token.

Platform File
apple (iOS, iPadOS, macOS) <slug>-wifi.mobileconfig: root CA, identity and an EAP-TLS Wi-Fi payload, signed when a profile-signing certificate is available.
windows <slug>-wifi-windows.zip: install.ps1, wifi-profile.xml, device.p12, CA certificates and README.txt.
android, other <slug>-wifi.p12: PKCS#12 with the full chain; the page shows the password and the settings to enter.
chromeos <slug>.onc: ONC file with the CA certificates, client certificate and Wi-Fi network.
linux <slug>-wifi-linux.zip: install.sh (NetworkManager), ca.pem, client.p12, client.pem, README.txt.

Limits apply per Airgate server instance:

  • per client IP: 300 page views per minute (including /apps/version), 60 sign-ins per minute, 60 certificate issues per hour, 60 downloads per minute (each of /download, the app files and /app/enroll);
  • per user: 10 failed passwords per 15 minutes, 10 certificate issues per hour.

A request over the limit answers 429 with a Retry-After header.

The AirEnroll app (Android) and agent (Windows) set up a device without manual steps. After the user chooses Use the AirEnroll app on the portal, Airgate issues the certificate (same device limit as a download) and stores the enrollment behind a one-time token, valid 10 minutes.

  • Android opens airgate://enroll?url=<url-encoded enroll URL>, with the fallback intent://enroll?url=<…>#Intent;scheme=airgate;package=com.airowire.airenroll;end.
  • Windows downloads AirEnroll-<token>.exe; the agent reads the token from its own file name. Tokens are URL-safe base64, 43 characters.

No cookie and no API token: the t query parameter is the credential. Cache-Control: no-store.

Status Body
200 The enrollment.
410 {"error": "…"}: the token was already used or has expired. The user starts again in the portal.
404 {"error": "…"}: unknown token.
429 Rate limit reached (60 per minute per IP), with Retry-After.
{"version": 1, "tenant": "contoso", "portal": "staff", "portal_name": "Staff devices",
"ssid": "Corp-WiFi", "eap": "TLS", "server_name": "radius.contoso.com",
"identity": "alice@contoso.com", "owner": "alice@contoso.com", "device_id": "5c2d…",
"ca_pem": "-----BEGIN CERTIFICATE-----…", "intermediate_pem": "-----BEGIN CERTIFICATE-----…",
"ca_sha1": "3b1f…", "pkcs12_b64": "MIIK…", "pkcs12_password": "…",
"not_after": "2027-11-19T10:00:00Z",
"my_devices_url": "https://airgate.contoso.com/byod/contoso/staff/devices"}
Field Meaning
version 1.
ssid The portal’s target_ssid.
eap TLS.
server_name RADIUS server name(s) to validate; several are joined with ;.
identity, owner The signed-in user, used as the EAP identity.
device_id The BYOD device ID.
ca_pem Root CA of the RADIUS server certificate chain.
intermediate_pem Other CA certificates of the client certificate chain (PEM, may be several or empty).
ca_sha1 SHA-1 thumbprint of ca_pem, lower-case hex.
pkcs12_b64, pkcs12_password Device key and certificate. Android gets legacy encryption with the full chain; Windows gets AES-256 without the root.
not_after Certificate expiry (RFC 3339, UTC).
my_devices_url The user’s My devices page.

Lists only the app files that are available. Cache-Control: no-store.

{"android": {"version": "1.0.3", "sha256": "…", "size": 5242880},
"windows": {"version": "1.0.3", "sha256": "…", "size": 3145728},
"windows_arm64": {"version": "1.0.3", "sha256": "…", "size": 3145728}}

When Airgate’s RADIUS service sees a BYOD certificate, the device’s endpoint gets the attributes BYOD (true), BYOD Owner, BYOD Device ID and BYOD Platform, and a CoA re-authentication is sent so the session picks up the BYOD rule. Access rules use them through the BYOD device condition. Revoking a device sets BYOD to false.

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