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.
Base path and permissions
Section titled “Base path and permissions”- 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 needsonboard: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 answers404.
Every admin change is written to the audit log (object type byod_portal for create, update and delete; byod_device for revoke).
Portals
Section titled “Portals”GET /byod-portals
Section titled “GET /byod-portals”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.
curl -s "$AIRGATE/api/v1/t/$TENANT/byod-portals" \ -H "Authorization: Bearer $TOKEN"POST /byod-portals
Section titled “POST /byod-portals”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. |
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.
GET /byod-portals/{id}
Section titled “GET /byod-portals/{id}”Permission: onboard:read
Returns one portal. Unknown ID: 404.
PUT /byod-portals/{id}
Section titled “PUT /byod-portals/{id}”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.
DELETE /byod-portals/{id}
Section titled “DELETE /byod-portals/{id}”Permission: onboard:write
Deletes the portal. Devices and their certificates stay; they lose the link to the portal. Response 204.
GET /byod-portals/{id}/preview
Section titled “GET /byod-portals/{id}/preview”Permission: onboard:read
Returns the portal’s landing page as HTML with sign-in disabled. Works for disabled portals too.
Devices
Section titled “Devices”GET /byod-devices
Section titled “GET /byod-devices”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}.
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.
GET /byod-devices/{id}
Section titled “GET /byod-devices/{id}”Permission: onboard:read
Returns one device. Unknown ID: 404.
POST /byod-devices/{id}/revoke
Section titled “POST /byod-devices/{id}/revoke”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.
curl -s -X POST "$AIRGATE/api/v1/t/$TENANT/byod-devices/5c2d…/revoke" \ -H "Authorization: Bearer $TOKEN"Statistics
Section titled “Statistics”GET /byod-stats
Section titled “GET /byod-stats”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}}Public portal routes
Section titled “Public portal routes”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.
Download artefacts
Section titled “Download artefacts”| 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. |
Rate limits
Section titled “Rate limits”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.
AirEnroll enrollment
Section titled “AirEnroll enrollment”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 fallbackintent://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.
GET /byod/{tenant}/{portal}/app/enroll
Section titled “GET /byod/{tenant}/{portal}/app/enroll”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. |
GET /byod/{tenant}/{portal}/apps/version
Section titled “GET /byod/{tenant}/{portal}/apps/version”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}}Endpoint attributes
Section titled “Endpoint attributes”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.