Guest access API
The guest access API manages guest accounts, captive portals and their skins, Wi-Fi passes (per-guest passphrases and vouchers), guest settings and the receipt log. It backs the console pages Guests › Wi-Fi passes, Guests › Guest accounts and Guests › Guest portal.
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. Every admin route needs a bearer token (see API overview) and one of these permissions:
| Permission | Grants |
|---|---|
guest:read |
List and read accounts, portals, skins, passes, settings and receipts. |
guest:write |
Create, change and delete them; reveal pass passphrases; send receipts and tests. |
The Guest Operator role has both. The captive portal itself (/portal/...) is public and is described in Public captive portal.
Lists use the standard envelope {"items": [...], "total": N} with ?q=&limit=&offset= (limit defaults to 50, at most 1000). Errors are {"error": "...", "code": "..."}. Every admin change is written to the audit log (object types guest, guest_portal, guest_settings, guest_pass); audit details never contain passwords.
Time inputs (start_time, expire_time and similar) accept RFC 3339, YYYY-MM-DD HH:MM[:SS], YYYY-MM-DDTHH:MM[:SS], YYYY-MM-DD (forms without a zone are read in the tenant’s time zone, default UTC) or epoch seconds / milliseconds. null or "" clears the value. Years outside 1970–9999 return 400.
Route summary
Section titled “Route summary”| Method | Path | Permission |
|---|---|---|
| GET | /guests |
guest:read |
| POST | /guests |
guest:write |
| POST | /guests/bulk |
guest:write |
| POST | /guests/bulk-action |
guest:write |
| POST | /guests/import |
guest:write |
| GET | /guests/stats |
guest:read |
| GET | /guests/{id} |
guest:read |
| PUT | /guests/{id} |
guest:write |
| DELETE | /guests/{id} |
guest:write |
| POST | /guests/{id}/extend |
guest:write |
| POST | /guests/{id}/send-receipt |
guest:write |
| POST | /guests/{id}/password |
guest:write |
| GET | /guest-portals |
guest:read |
| POST | /guest-portals |
guest:write |
| GET | /guest-portals/{id} |
guest:read |
| PUT | /guest-portals/{id} |
guest:write |
| DELETE | /guest-portals/{id} |
guest:write |
| GET | /guest-portals/{id}/preview |
guest:read |
| POST | /guest-portals/{id}/clone |
guest:write |
| GET | /guest-skins |
guest:read |
| POST | /guest-skins |
guest:write |
| GET | /guest-skins/{id} |
guest:read |
| PUT | /guest-skins/{id} |
guest:write |
| DELETE | /guest-skins/{id} |
guest:write |
| GET | /guest-passes |
guest:read |
| POST | /guest-passes |
guest:write |
| POST | /guest-passes/vouchers |
guest:write |
| GET | /guest-passes/daily |
guest:write |
| GET | /guest-passes/{id} |
guest:read |
| GET | /guest-passes/{id}/card |
guest:write |
| POST | /guest-passes/{id}/revoke |
guest:write |
| GET | /guest-settings |
guest:read |
| PUT | /guest-settings |
guest:write |
| POST | /guest-settings/test |
guest:write |
| GET | /guest-receipts |
guest:read |
Guest accounts
Section titled “Guest accounts”Guest account object
Section titled “Guest account object”{ "id": "1d7a3c2e-2b8e-4c1c-9c50-3f6a51b0f7e0", "tenant_id": "9eac1cf6-70ad-4e7d-b5a5-c0aeca76528d", "username": "ann@contoso.com", "name": "Ann Visitor", "email": "ann@contoso.com", "phone": "+15550100000", "company": "Fabrikam", "sponsor_name": "Alice Host", "sponsor_email": "alice@contoso.com", "role_id": "0b0c5d1e-…", "role": "[Guest]", "state": "active", "enabled": true, "start_time": null, "expire_time": "2026-10-29T18:00:00Z", "remaining_seconds": 14390, "expire_action": "delete_logout", "do_expire": 4, "expire_postlogin": 0, "simultaneous_use": 2, "no_password": false, "has_password": true, "portal_id": null, "portal": "", "source": "admin", "created_by": "admin@contoso.com", "custom_fields": {"visit_reason": "meeting"}, "mac": "a4:83:e7:12:34:56", "notes": "", "first_login_at": "2026-10-29T14:01:02Z", "last_login_at": "2026-10-29T14:01:02Z", "expired_at": null, "created_at": "2026-10-29T14:00:00Z", "updated_at": "2026-10-29T14:01:02Z"}| Field | Meaning |
|---|---|
state |
pending (not active, set by an operator), active, disabled or expired (set when the account expires; the record is kept). |
enabled |
Computed: state is active and now is inside the start_time / expire_time window. |
remaining_seconds |
Computed: seconds until expire_time; 0 when past, null when the account never expires. |
expire_action / do_expire |
What happens at expiry: none (0, the account just stops authenticating), disable (1), disable_logout (2, also disconnects the guest’s sessions), delete (3), delete_logout (4, default). Inputs also accept do_expire 0–4 and logout (= delete_logout). |
expire_postlogin |
Minutes after the first login after which the account expires; 0 = off. |
source |
admin, bulk, import, self_registration or accept_terms. Older accounts may show sponsored. |
mac |
The guest’s registered or last-used device, set at portal login and on the first RADIUS accept that carries a MAC. |
Passwords are never returned, except as password in the create, bulk-create, import and password-reset responses, and only when Airgate generated the password.
GET /guests
Section titled “GET /guests”Permission: guest:read
| Query parameter | Type | Meaning |
|---|---|---|
q |
string | Substring over user name, name, email, company, phone, sponsor name and sponsor email. |
state |
list | Comma-separated states. Unknown values return 400. |
status |
list | Computed status: enabled (can authenticate now) or scheduled (active, start_time in the future). |
portal |
string | Portal ID or slug. |
sponsor |
string | Sponsor email (exact, case-insensitive). |
source |
list | Comma-separated sources. |
role |
string | Role ID or name. |
mac |
string | MAC address in any notation. |
expires_before |
time | Accounts that expire before this time. |
sort |
list | Any of username, name, email, company, state, created_at, updated_at, expire_time, start_time, last_login_at, sponsor_email; prefix - (or suffix :desc) for descending. Default -created_at. |
limit, offset |
integer | Paging. |
curl -s "$AIRGATE/api/v1/t/$TENANT/guests?status=enabled&sort=expire_time" \ -H "Authorization: Bearer $TOKEN"Response 200: {"items": [guest account…], "total": N}.
POST /guests
Section titled “POST /guests”Permission: guest:write
| Field | Type | Meaning |
|---|---|---|
username |
string | Empty: the email when given, otherwise generated from the tenant defaults. Must not be a MAC address; at most 253 characters. |
password |
string | Empty: generated (tenant defaults) and returned once. 4 characters to 72 bytes. |
no_password |
boolean | true creates a password-less account (web login one-time passwords or MAC caching only). |
name |
string | Visitor name (alias visitor_name). |
email |
string | Visitor email. |
phone |
string | Visitor phone (alias visitor_phone). |
company |
string | Visitor company (alias visitor_company). |
sponsor_name, sponsor_email |
string | The person the guest is visiting. |
role_id |
string or number | Role UUID, numeric role ID (from guest settings role_ids) or role name; alias role. Default: the tenant’s [Guest] role. |
state |
string | pending, active or disabled (or enabled: true/false). |
start_time |
time | When the account starts working. |
expire_time |
time | Expiry. Alternatively expire_after in hours from now (or from start_time). Without either, the tenant default lifetime applies. |
expire_action |
string | See the object table (or do_expire). |
expire_postlogin |
integer | Minutes after first login. |
simultaneous_use |
integer | 0–1000. |
custom_fields |
object | At most 64 fields; names at most 64 characters, values (string, number or boolean) at most 1024 characters. |
mac |
string | Device MAC address in any notation. |
notes |
string | Free text. |
portal_id |
string | Portal ID or slug (used for receipt templates). |
send_receipt |
array | ["email"], ["sms"] or both: send the receipt after creating. |
curl -s -X POST "$AIRGATE/api/v1/t/$TENANT/guests" \ -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \ -d '{"name": "Ann Visitor", "email": "ann@contoso.com", "company": "Fabrikam", "sponsor_email": "alice@contoso.com", "expire_after": 8, "send_receipt": ["email"]}'Response 201: the guest account, plus password when it was generated and receipts (delivery results) when send_receipt was given. A duplicate user name (case-insensitive) returns 409. Validation errors return 400.
GET /guests/{id}
Section titled “GET /guests/{id}”Permission: guest:read. Response 200: the guest account.
PUT /guests/{id}
Section titled “PUT /guests/{id}”Permission: guest:write
Send any subset of the create fields; omitted fields are kept. A non-empty password (not "********") replaces the credentials and revokes outstanding web-login one-time passwords; no_password: true removes them; role_id: null clears the role. expire_time must be in the future (use /extend to revive an expired account).
Side effects:
- An active account that becomes
pending,disabledorexpiredloses its MAC caches. - When the role of an active account changes, its cached devices get the new role and Airgate sends a CoA re-authentication for each.
Response 200: the guest account.
DELETE /guests/{id}
Section titled “DELETE /guests/{id}”Permission: guest:write
Deletes the account and revokes its MAC caches. With ?disconnect=true Airgate also sends a CoA Disconnect-Request for every MAC address the guest may be online with. Response 204.
POST /guests/bulk
Section titled “POST /guests/bulk”Permission: guest:write
Creates count (1–500) accounts with generated credentials. Accepts every create field except username, password, email and mac, plus:
| Field | Type | Meaning |
|---|---|---|
count |
integer | Number of accounts, 1–500. |
username_prefix |
string | Prefix of the generated user names. |
username_length |
integer | Length of the random part. |
password_mode |
string | digits, letters or alnum. |
password_length |
integer | Length of the generated passwords. |
{"count": 50, "username_prefix": "conf-", "username_length": 6, "password_mode": "alnum", "password_length": 10, "company": "Conference", "role": "[Guest]", "expire_after": 24, "expire_action": "delete", "custom_fields": {"event": "Expo"}}Response 200: {"items": [guest account with "password"…], "total": N}, sorted by user name.
POST /guests/bulk-action
Section titled “POST /guests/bulk-action”Permission: guest:write
Applies one action to up to 500 accounts. Each ID is processed exactly like the single-account route.
| Field | Type | Meaning |
|---|---|---|
ids |
array | 1–500 account IDs (duplicates removed). |
action |
string | state, delete, extend or send_receipt. |
state |
string | For state: pending, active, disabled or expired. |
disconnect |
boolean | For delete: also disconnect the guest’s devices. |
minutes, hours, days, expire_time |
For extend: as POST /guests/{id}/extend. |
|
channels, include_password |
For send_receipt: as POST /guests/{id}/send-receipt. Receipts go only to each guest’s own email / phone (at most 100 IDs). |
{"ids": ["…", "…"], "action": "extend", "days": 1}Response 200:
{"action": "state", "total": 3, "succeeded": 2, "failed": 1, "items": [{"id": "…", "ok": true, "guest": {"…": "…"}}, {"id": "…", "ok": false, "code": "not_found", "error": "guest not found"}]}Items keep the request order. code is not_found, bad_request, conflict or internal.
POST /guests/import
Section titled “POST /guests/import”Permission: guest:write
Imports named visitor accounts from a CSV file. Send the file as the request body (text/csv) or as multipart/form-data in the field file. Limits: 5 MiB and 1000 accounts per file.
| Option (query or form field) | Meaning |
|---|---|
dry_run |
true validates only; nothing is written. |
role |
Default role (ID, numeric ID or name). |
expire_after |
Default lifetime in hours (0–87600). |
expire_action |
Default expiry action. |
portal |
Portal ID or slug the accounts belong to. |
The file is UTF-8, comma-, semicolon- or tab-separated (detected from the header). Header names are case-insensitive. Recognised columns: username (user, user_name, login), password, name (visitor_name, full_name), email (visitor_email, email_address), phone (visitor_phone, mobile), company (visitor_company), sponsor_name, sponsor_email, role (role_id, role_name), start_time, expire_time, expire_after, expire_action (do_expire), expire_postlogin, simultaneous_use, notes, mac (mac_address), state, enabled, no_password. Any other column becomes a custom field. A user name that already exists is skipped; the import never updates accounts.
curl -s -X POST "$AIRGATE/api/v1/t/$TENANT/guests/import?dry_run=true&expire_after=24" \ -H "Authorization: Bearer $TOKEN" -H "Content-Type: text/csv" --data-binary @visitors.csvResponse 200:
{"dry_run": false, "total": 3, "created": 1, "skipped": 1, "failed": 1, "items": [{"row": 2, "username": "alice", "status": "created", "id": "…"}, {"row": 3, "username": "taken", "status": "exists", "error": "a guest with this user name already exists"}, {"row": 4, "username": "carol", "status": "error", "error": "email is not a valid e-mail address"}]}row is the CSV line (the header is row 1). In a dry run status is valid, exists or error.
GET /guests/stats
Section titled “GET /guests/stats”Permission: guest:read. Optional ?portal=<id|slug>.
{"total": 412, "by_state": {"pending": 3, "active": 380, "disabled": 9, "expired": 20}, "enabled": 371, "scheduled": 9, "expiring_24h": 57, "created_24h": 64, "logged_in_24h": 140, "by_source": {"admin": 12, "bulk": 100, "self_registration": 300}}POST /guests/{id}/extend
Section titled “POST /guests/{id}/extend”Permission: guest:write
{"hours": 4} (any of minutes, hours, days, summed; extends from the later of now and the current expiry) or {"expire_time": "…"}. An expired account becomes active. Response 200: the guest account.
POST /guests/{id}/send-receipt
Section titled “POST /guests/{id}/send-receipt”Permission: guest:write
| Field | Type | Meaning |
|---|---|---|
channels |
array | email, sms. Default: every channel the guest has an address for (400 when none). |
email, phone |
string | Override the recipient. |
include_password |
boolean | Default true. |
Response 200:
{"items": [{"channel": "email", "recipient": "ann@contoso.com", "status": "sent"}, {"channel": "sms", "recipient": "+15550100000", "status": "skipped", "error": "SMS gateway is not configured"}], "total": 2}status is sent, failed or skipped.
POST /guests/{id}/password
Section titled “POST /guests/{id}/password”Permission: guest:write
Optional body {"password": "…"}. Without it Airgate generates a password and returns it as password in the account object. Response 200.
Guest portals
Section titled “Guest portals”Portal object
Section titled “Portal object”{ "id": "…", "tenant_id": "…", "slug": "guest", "name": "Corp-Guest", "description": "", "type": "self_registration", "enabled": true, "url": "https://airgate.contoso.com/portal/contoso/guest", "branding": {"skin": "classic", "title": "Guest Wi-Fi", "heading": "Welcome", "message": "Register to get online.", "logo": "data:image/png;base64,…", "primary_color": "#0b5fff", "background_color": "#f4f6fb", "text_color": "#1d2433", "footer": "", "submit_label": ""}, "fields": [{"name": "name", "label": "Full name", "type": "text", "required": true, "max_length": 128}], "terms": "By using this network …", "require_terms": true, "auth_service_id": null, "auth_service": "", "role_id": "…", "role": "[Guest]", "account_lifetime_minutes": 1440, "expire_action": "delete_logout", "mac_caching_days": 1, "mac_binding": "session", "post_login_action": "coa", "vendor": "auto", "vendor_config": {"coa_kind": "reauth", "login_url": "", "allowed_login_hosts": [], "login_delay_seconds": 0, "grant_duration_minutes": 0, "mist_api_secret": "", "url_hash_key": "********"}, "receipt": {"show_credentials": true, "email": {"enabled": true, "subject": "Your guest network account", "body": "Hello {{name}}, …"}, "sms": {"enabled": false, "body": "Wi-Fi login {{username}} / {{password}}"}}, "allowed_email_domains": [], "username_mode": "email", "password_mode": "digits", "password_length": 8, "registration_limit_hours": 0, "success_url": "", "created_at": "…", "updated_at": "…"}| Field | Meaning |
|---|---|
type |
login (existing accounts sign in), self_registration (visitors create their own account) or accept_terms (click-through; a password-less account per device). |
slug |
URL segment: lower-case letters, digits and -, at most 63 characters, unique in the tenant. sponsor, static, assets and api are reserved. |
url |
Read-only public URL. Configure it as the captive-portal / redirect URL on the switch, controller or AP. |
branding |
Texts, skin (a built-in skin key or a tenant skin ID), colours (#rgb or #rrggbb) and logo (a data:image/… URI, at most 256 KiB). The portal’s colours and logo override the skin’s. |
fields |
Registration form, at most 30 fields. type is text, email, tel, select (needs options), checkbox or textarea. The names name, email, phone, company, sponsor_name, sponsor_email map to account fields; any other name becomes a custom field. |
terms, require_terms |
Terms of use (at most 64 KiB) and whether the form requires accepting them. |
auth_service_id |
Optional WEBAUTH or APPLICATION access policy: portal logins then authenticate through that policy’s directories, role mapping and enforcement. Without it, logins check the guest accounts only. |
role_id / role |
Role of accounts the portal creates. Default [Guest]. |
account_lifetime_minutes |
Lifetime of created accounts (0 = no expiry). |
expire_action |
Expiry action of created accounts. |
mac_caching_days |
0–3650. How long the device stays authorised after login; 0 = until the account expires (capped at 30 days). Never beyond the account expiry. |
mac_binding |
How the portal trusts the client MAC in the redirect URL: session (default), signed or off. See MAC trust. |
post_login_action |
coa (MAC caching plus Change of Authorization) or web_login (posts the user name and a one-time password to the NAD’s login URL, or uses the vendor’s grant URL). |
vendor |
auto, aruba, aruba-switch, cisco, cisco-wlc, meraki, meraki-grant, ruckus, fortinet, mist, arista, extreme, extreme-xiq, unifi or generic. |
vendor_config.coa_kind |
Post-login CoA: reauth (default), bounce (wired VLAN change) or disconnect (wireless VLAN change). |
vendor_config.login_url, login_method, username_field, password_field, extra_fields |
Web-login target for generic. |
vendor_config.allowed_login_hosts |
Extra hosts the portal may post credentials to (host, *.suffix, IP or CIDR). The vendor’s own login hosts and the tenant’s NAD addresses are always allowed. |
vendor_config.login_delay_seconds |
0–300 seconds the success page waits before continuing. |
vendor_config.grant_duration_minutes |
Meraki / Mist grant duration (0 = the remaining account lifetime). |
vendor_config.mist_api_secret, vendor_config.url_hash_key |
Secrets, stored sealed and returned as "********". Sending the mask keeps the stored value; "" clears it. |
receipt |
show_credentials on the receipt page, email / SMS receipt templates, and sponsor (below). |
allowed_email_domains |
Registration email domains (sub-domains included, at most 100). Empty = any. |
username_mode |
email, phone or random. |
password_mode, password_length |
digits, letters, alnum or none (password-less); length 4–64. |
registration_limit_hours |
One registration per email, phone or device per portal in this window (0 = off). |
success_url |
Where the browser goes after login (otherwise the originally requested URL). |
Sponsor notification (receipt.sponsor). {"enabled": true, "label": "Who are you visiting?", "sponsors": [{"name": "Alice Host", "email": "alice@contoso.com"}]} (at most 500 sponsors). Works on a self-registration portal with passwords: the visitor picks a sponsor by name, and the generated password is sent to the sponsor through the tenant’s Microsoft Teams workflow (guest settings teams) instead of being shown to the visitor.
GET /guest-portals
Section titled “GET /guest-portals”Permission: guest:read
| Query parameter | Type | Meaning |
|---|---|---|
q |
string | Search. |
type |
list | Comma-separated portal types. |
enabled |
boolean | Filter by state. |
summary |
boolean | 1 returns light items without branding, fields, terms, vendor_config and receipt. |
Every item carries account_count. Response 200: list envelope.
POST /guest-portals
Section titled “POST /guest-portals”Permission: guest:write
Body: portal fields. Unset fields start from the defaults (self_registration, enabled, role [Guest]). Response 201: the portal. A duplicate slug returns 409. signed MAC binding needs vendor aruba, aruba-switch or auto and a vendor_config.url_hash_key.
curl -s -X POST "$AIRGATE/api/v1/t/$TENANT/guest-portals" \ -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \ -d '{"slug": "lobby", "name": "Lobby Wi-Fi", "type": "self_registration", "account_lifetime_minutes": 480, "post_login_action": "coa", "vendor": "auto"}'GET /guest-portals/{id} · PUT /guest-portals/{id} · DELETE /guest-portals/{id}
Section titled “GET /guest-portals/{id} · PUT /guest-portals/{id} · DELETE /guest-portals/{id}”Permission: guest:read (GET), guest:write (PUT, DELETE)
PUT replaces each top-level key present in the body and keeps the others; read-only fields (id, url, account_count and similar) are ignored. DELETE ends the portal’s sessions; accounts and devices keep working. Response 200 (GET, PUT) or 204 (DELETE).
GET /guest-portals/{id}/preview
Section titled “GET /guest-portals/{id}/preview”Permission: guest:read
Returns a one-hour preview link that renders the portal (also when disabled) with a “Preview” banner; forms cannot be submitted. A new call replaces the previous link.
{"url": "https://airgate.contoso.com/portal/contoso/guest?preview=Zx…", "public_url": "https://airgate.contoso.com/portal/contoso/guest", "example_url": "https://airgate.contoso.com/portal/contoso/guest?mac=00:11:22:33:44:55&ip=10.0.0.10&ssid=Corp-Guest&url=…&preview=Zx…", "expires_at": "2026-10-29T15:00:00Z"}POST /guest-portals/{id}/clone
Section titled “POST /guest-portals/{id}/clone”Permission: guest:write
Optional body {"slug": "…", "name": "…"}. Defaults: name <name> (copy), slug <slug>-copy. Everything is copied, including sealed secrets. The copy is created disabled. Response 201: the new portal; a taken slug returns 409.
Portal skins
Section titled “Portal skins”A portal’s look comes from its skin (branding.skin). Built-in skins are read-only: classic (default), airowire, minimal, hospitality and dark. Tenant skins have these fields:
| Field | Type | Meaning |
|---|---|---|
name, description |
string | Display name and description. |
based_on |
string | Skin to copy on create; body fields override the copy. |
css |
string | At most 64 KiB, appended after the base styles. Must not contain </, @import, expression( or javascript:. |
header_html, footer_html |
string | At most 32 KiB each, placed before and after the page content. Scripts are blocked by the page’s content security policy. |
logo, background_image |
string | data: URIs, at most 1 MiB each. |
primary_color, background_color, text_color |
string | Colours. |
| Method | Path | Permission | Notes |
|---|---|---|---|
| GET | /guest-skins |
guest:read |
Built-in skins first, then tenant skins. |
| GET | /guest-skins/{id} |
guest:read |
|
| POST | /guest-skins |
guest:write |
201. |
| PUT | /guest-skins/{id} |
guest:write |
Tenant skins only. |
| DELETE | /guest-skins/{id} |
guest:write |
Tenant skins only; 409 while a portal uses the skin. |
Wi-Fi passes
Section titled “Wi-Fi passes”Wi-Fi passes give each guest (or voucher) its own WPA2-Personal passphrase on a guest SSID, without a captive portal. Configure them in the wifi_passes section of the guest settings.
Pass object
Section titled “Pass object”{"id": "…", "tenant_id": "…", "kind": "guest", "batch_id": null, "name": "Ann Visitor", "email": "ann@contoso.com", "phone": "", "company": "Fabrikam", "notes": "", "ssid": "Corp-Guest", "mode": "per_guest", "devices": 3, "valid_from": "…", "valid_until": "…", "revoked_at": null, "revoked_by": "", "created_by": "frontdesk@contoso.com", "created_at": "…", "status": "active", "psk": "********"}status is computed: revoked, expired, scheduled or active. kind is guest or voucher. psk is masked in lists and reads.
GET /guest-passes
Section titled “GET /guest-passes”Permission: guest:read
| Query parameter | Type | Meaning |
|---|---|---|
status |
list | Any of active, scheduled, expired, revoked. |
kind |
string | guest or voucher. |
batch_id |
string | Vouchers of one batch. |
q, sort, limit, offset |
Search, sort and paging. |
POST /guest-passes
Section titled “POST /guest-passes”Permission: guest:write
| Field | Type | Meaning |
|---|---|---|
name |
string | Required, at most 128 characters. |
email, phone, company, notes |
string | Optional visitor details. |
hours |
integer | Validity, 1–720 (default: wifi_passes.default_hours). |
curl -s -X POST "$AIRGATE/api/v1/t/$TENANT/guest-passes" \ -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \ -d '{"name": "Ann Visitor", "company": "Fabrikam", "hours": 8}'Response 201: the pass with the clear psk and qr (WIFI:T:WPA;S:<ssid>;P:<psk>;;), plus psk_valid_until in shared_daily mode. Returns 409 when Wi-Fi passes are not configured (no SSID).
POST /guest-passes/vouchers
Section titled “POST /guest-passes/vouchers”Permission: guest:write
{"count": 1-200, "hours": 24, "note": "Training day"}. Response 201: {"batch_id": "…", "items": [pass with psk and qr…], "total": n}.
GET /guest-passes/daily
Section titled “GET /guest-passes/daily”Permission: guest:write
In shared_daily mode returns the passphrase of the day: {"ssid", "mode", "psk", "qr", "valid_until", "devices"}. Returns 409 in per_guest mode.
GET /guest-passes/{id}
Section titled “GET /guest-passes/{id}”Permission: guest:read. The pass with the passphrase masked.
GET /guest-passes/{id}/card
Section titled “GET /guest-passes/{id}/card”Permission: guest:write
The pass with psk and qr, for reprinting. Recorded in the audit log as reveal. Returns 409 for revoked or expired passes.
POST /guest-passes/{id}/revoke
Section titled “POST /guest-passes/{id}/revoke”Permission: guest:write
Revokes the pass (repeating it has no effect). The passphrase is no longer sent from the next MAC authentication on; devices already connected re-authenticate within an hour. Response 200: the pass.
Guest settings
Section titled “Guest settings”GET /guest-settings
Section titled “GET /guest-settings”Permission: guest:read
{ "sms": {"enabled": false, "provider": "generic", "url": "", "method": "POST", "content_type": "", "body": "", "headers": {}, "auth_type": "none", "username": "", "password": "", "token": "", "account_sid": "", "from": "", "success_regex": "", "timeout_sec": 10, "rate_limit_per_hour": 5}, "email": {"enabled": true, "from": "", "reply_to": "", "subject_prefix": ""}, "role_ids": {"1": "[Contractor]", "2": "[Guest]", "3": "[Employee]"}, "defaults": {"username_prefix": "g", "username_length": 7, "password_mode": "digits", "password_length": 8, "lifetime_minutes": 0, "expire_action": "delete_logout", "expired_retention_days": 90, "receipt": {"show_credentials": false, "email": {"enabled": false, "subject": "…", "body": "…"}, "sms": {"enabled": false, "body": "…"}}, "mac_cache_expiry_action": "reauth"}, "wifi_passes": {"ssid": "Corp-Guest", "mode": "per_guest", "default_hours": 24, "max_active": 20, "psk_length": 12, "devices_per_pass": 3}, "teams": {"enabled": false, "workflow_url": ""}, "updated_at": "2026-10-29T14:00:00Z"}| Section | Meaning |
|---|---|
sms |
SMS gateway. provider is generic (HTTP request to url with {{to}}, {{message}}, {{from}} placeholders; method POST or GET; auth_type none, basic or bearer; success = HTTP 2xx and, when set, success_regex matching the body) or twilio (account_sid, token, from). password, token and credential-like header values are sealed and returned as "********". rate_limit_per_hour limits messages per recipient number. |
email |
enabled: false stops all guest email of the tenant. Mail is always sent from the platform sender address; the tenant address in reply_to (or from) becomes the Reply-To. subject_prefix prefixes every subject. |
role_ids |
Numeric role IDs mapped to role names, accepted wherever a role is given. |
defaults |
Generated credentials, lifetime_minutes (0–5256000, 0 = no expiry), expire_action, expired_retention_days (0–36500; expired accounts are deleted after this, 0 = 90), receipt templates for accounts without a portal, and mac_cache_expiry_action (reauth, disconnect or none: what happens to a device still online when its guest MAC cache lapses). |
wifi_passes |
ssid (exact broadcast name; empty turns passes off), mode (per_guest or shared_daily), default_hours (1–720), max_active (1–100 passphrases sent to the AP), psk_length (8–63), devices_per_pass (printed on the card). |
teams |
enabled, workflow_url (an https Power Automate workflow URL; sealed and returned masked). Used for sponsor notifications. |
PUT /guest-settings
Section titled “PUT /guest-settings”Permission: guest:write
Each section present (sms, email, role_ids, defaults, wifi_passes, teams) replaces the stored one; absent sections are kept. Send a whole section as returned by GET. Invalid values return 400. Response 200: the settings.
POST /guest-settings/test
Section titled “POST /guest-settings/test”Permission: guest:write
{"channel": "email" | "sms" | "teams", "to": "…"}. For teams, to is the sponsor’s user principal name and Airgate sends a sample sponsor card.
{"channel": "sms", "recipient": "+15550100000", "status": "sent"}GET /guest-receipts
Section titled “GET /guest-receipts”Permission: guest:read
The receipt and notification delivery log, newest first, kept 180 days. Filters: guest_id, status (comma list), channel (comma list), q (user name, recipient or error). Message bodies are never stored.
{"items": [{"id": 42, "guest_id": "…", "username": "ann@contoso.com", "channel": "email", "kind": "receipt", "recipient": "ann@contoso.com", "status": "sent", "error": "", "created_at": "…"}], "total": 1}Receipt templates
Section titled “Receipt templates”Templates use {{key}} placeholders (case-insensitive; unknown keys render empty): username, password, name, email, phone, company, sponsor_name, sponsor_email, role, expire_time, start_time, portal, mac and every custom field.
Public captive portal
Section titled “Public captive portal”These routes are on the public listener and need no API token. They serve server-rendered HTML pages for guests’ browsers; you do not call them from scripts. {tenant} is the tenant slug or ID, {portal} the portal slug.
| Method | Path | Purpose |
|---|---|---|
| GET | /portal/{tenant}/{portal} |
Landing page. The switch, controller or AP redirects the browser here with its parameters (client MAC, IP, SSID, original URL, login target). |
| POST | /portal/{tenant}/{portal}/login |
Sign in with a guest account (form fields sid, csrf, username, password, accept_terms). |
| POST | /portal/{tenant}/{portal}/register |
Self-registration (the portal’s fields). |
| POST | /portal/{tenant}/{portal}/accept |
Accept-terms portals: creates or renews the device’s password-less account. |
| GET | /portal/{tenant}/{portal}/status?sid= |
JSON state of the portal session: {"state": "new" | "authorized" | "denied" | "failed", "message", "coa_result", "next"}. |
| GET | /portal/{tenant}/{portal}/continue?sid= |
Runs the post-login action of an authorised session. |
| POST | /portal/{tenant}/{portal}/logout |
Ends the portal login of the session. |
| GET | /portal/{tenant}/{portal}/capport/{sid} |
Captive-portal API (RFC 8908), application/captive+json. |
Every sign-in attempt appears in Monitor › Sign-in log with protocol WEBAUTH. Portal pages are rate-limited per client address (120 landings, 60 logins and 30 registrations per minute; 10 failed passwords per user name per 15 minutes).
MAC trust
Section titled “MAC trust”The client MAC in a redirect URL can be typed by anyone, so the portal only binds a login to a device it trusts (mac_binding):
session(default): the MAC must have RADIUS activity in the tenant within the last 15 minutes.signed: additionally, the URL must carry a valid Aruba redirect-URL hash made withvendor_config.url_hash_key.off: the MAC is trusted as sent. Use only on closed networks.
When the MAC is not trusted, the visitor can still sign in, but Airgate does not cache the MAC, bind the device or send a CoA; the page shows “Device could not be verified”. A device an administrator disabled is never authorised by a portal login.