Skip to content

REST API overview

Everything you can do in the Airgate console you can also do through the REST API: the console itself is a client of it. This page explains how to get credentials, how URLs are built, and the conventions every module follows. The module pages in this section list each endpoint.

All API routes live under /api/v1 on your Airgate console address, for example https://airgate.contoso.com/api/v1. On an appliance this is the Console address you entered at first boot; on Airgate Cloud it is the address you sign in to.

Prefix What it holds Who can call it
/api/v1/t/{tenant}/… Everything that belongs to one tenant: policies, directories, devices, guests, certificates, logs Administrators and API clients of that tenant; platform administrators
/api/v1/platform/… Cross-tenant operations: tenants, platform audit log, software update, backups Platform administrators only
/api/v1/auth/…, /api/v1/oauth/token Sign-in, token issue, the signed-in principal Anyone (sign-in) or any signed-in principal

{tenant} is the tenant’s slug (for example contoso) or its ID. A principal that may not access a tenant gets 404 not_found, the same as for a tenant that does not exist. A disabled tenant answers 403 forbidden to everyone except platform administrators.

A few modules also serve unauthenticated public endpoints outside /api/v1 with their own authentication (guest and BYOD portals, OCSP, CRL, SCEP, the site connector API). Their module pages give the full paths.

Every /api/v1 request except sign-in and token issue needs a bearer token:

Authorization: Bearer <access token>

There are two kinds of principals:

Principal How it gets a token Token lifetime
API client (scripts, integrations) OAuth 2.0 client credentials grant at POST /api/v1/oauth/token 1 hour
Administrator (a person) POST /api/v1/auth/login with email and password, or console single sign-on 8 hours

Use API clients for automation. They belong to one tenant, have a role like an administrator, and never need a password or MFA prompt.

  1. In the console, go to Settings › API keys.
  2. Select Create API client (you need the admin:write permission, for example the Tenant Administrator role).
  3. Enter a Name and optional description, and choose the Scope (operator profile): the role whose permissions the client gets. You can only grant a role whose permissions you hold yourself.
  4. Copy the Client ID and the Client secret. The secret is shown only once: Airgate stores only a hash of it. Keep it in your secret store.

The client’s drawer shows the Token endpoint, the API base URL, the grant type client_credentials and a ready-to-use curl command.

POST /api/v1/oauth/token implements the OAuth 2.0 client credentials grant (RFC 6749 §4.4). It accepts a form body or a JSON body, and the client credentials either in the body or with HTTP Basic authentication.

Terminal window
export AIRGATE=https://airgate.contoso.com
export CLIENT_ID=nac_xxxxxxxxxxxx
export CLIENT_SECRET='…' # from your secret store
curl -s -X POST "$AIRGATE/api/v1/oauth/token" \
-u "$CLIENT_ID:$CLIENT_SECRET" \
-d grant_type=client_credentials
{"access_token": "eyJhbGciOi…", "token_type": "Bearer", "expires_in": 3600}
Field Type Meaning
grant_type string Must be client_credentials
client_id string The client ID (or the HTTP Basic user name)
client_secret string The client secret (or the HTTP Basic password)
Status Body Cause
200 token response above Success
400 {"error": "unsupported_grant_type"} Any grant type other than client_credentials
401 {"error": "invalid_client"} Unknown client ID, wrong secret, client or tenant disabled
429 {"error": "too many failed attempts", "code": "locked"} 10 failed attempts for this client ID; retry 15 minutes after the last failure

Request a new token when the current one is about to expire; there is no refresh token.

Terminal window
TOKEN=$(curl -s -X POST "$AIRGATE/api/v1/oauth/token" \
-u "$CLIENT_ID:$CLIENT_SECRET" -d grant_type=client_credentials | jq -r .access_token)
export TENANT=contoso
curl -s "$AIRGATE/api/v1/t/$TENANT/nads?limit=10" -H "Authorization: Bearer $TOKEN"

People sign in with POST /api/v1/auth/login:

Terminal window
curl -s -X POST "$AIRGATE/api/v1/auth/login" \
-H "Content-Type: application/json" \
-d '{"email": "alice@contoso.com", "password": "…"}'

The response holds token, expires_at and principal (see GET /auth/me). Ten failed attempts for one account lock it for 15 minutes after the last failure (429, code locked). Accounts that sign in through an identity provider use the console single sign-on API instead. Use API clients, not administrator passwords, in scripts.

Tokens are signed and not stored, so Airgate revokes them by time: every token issued to a principal before its cut-off time stops working. The cut-off moves forward when:

  • the principal calls POST /api/v1/auth/logout (all its tokens, not only the current one);
  • an administrator changes the principal’s role, disables it, or changes its password;
  • an API client’s secret is rotated or the client is disabled;
  • an administrator changes their own password.

Deleting an administrator or API client, or disabling its tenant, also makes its tokens invalid at once.

Each route requires one permission. A principal has the permissions of its role:

Permission Allows
policy:read / policy:write Access policies, enforcement profiles, authentication methods, directories’ policy use, network devices, site connectors
identity:read / identity:write Local users, devices (endpoints), roles, MAC lists
guest:read / guest:write Guest accounts, Wi-Fi passes, guest portals
onboard:read / onboard:write Certificate authorities, issued certificates, BYOD
monitor:read Sign-in log, sessions, events, reports, logs
monitor:coa Send Change of Authorization (reauthenticate, disconnect, bounce)
admin:read / admin:write Administrators, API keys, single sign-on, webhooks, log export, tenant settings, audit log
platform:admin Tenants and the platform routes
Role Console label Permissions
tenant_admin Tenant Administrator Every tenant permission
network_admin Network Administrator Every tenant permission except admin:write
helpdesk Help Desk policy:read, identity:read, identity:write, guest:read, guest:write, onboard:read, monitor:read, monitor:coa
guest_operator Guest Operator guest:read, guest:write
read_only Read-only Administrator policy:read, identity:read, guest:read, onboard:read, monitor:read, admin:read
platform_admin Platform Administrator platform:admin and every tenant permission in every tenant

GET /api/v1/auth/roles returns this catalogue as JSON. API clients can have any role except platform_admin, so API clients cannot call /api/v1/platform routes.

A request without the required permission gets 403 with code forbidden and the message missing permission <perm>.

  • Send JSON bodies with Content-Type: application/json. Bodies are limited to 8 MiB (file import endpoints document their own limit).
  • Unknown fields in a body are ignored, so you can send back an object you read (with id, created_at and other read-only fields).
  • On PUT updates, most modules treat an absent field as “keep the current value”; the module pages say where a PUT replaces the whole object.
  • IDs are UUIDs. Times are RFC 3339 in UTC (2026-11-19T08:30:00Z).
  • Secrets you set (shared secrets, bind passwords, client secrets) are never returned. Responses show them masked, usually as ********; sending the mask back keeps the stored value.
  • A request that takes longer than 60 seconds is cancelled.

List endpoints return one envelope:

{"items": [ … ], "total": 128}

total is the number of matching objects, not the number in this page. Paged lists accept these query parameters:

Parameter Default Meaning
limit 50 Page size, at most 1000
offset 0 Number of matching objects to skip
q none Free-text search; the module page says which fields it matches
sort module default Sort key; the module page lists the accepted keys

Some small collections (for example administrators and API clients) always return every item. Module-specific filters, such as status= or from= / to= time ranges, are listed with each endpoint.

Terminal window
# second page of 100 devices that match "lobby"
curl -s "$AIRGATE/api/v1/t/$TENANT/endpoints?q=lobby&limit=100&offset=100" \
-H "Authorization: Bearer $TOKEN"

Errors use one envelope with a human-readable message and a stable machine code:

{"error": "missing permission policy:write", "code": "forbidden"}
Status code Meaning
400 bad_request Invalid JSON, missing or invalid field, failed validation
401 unauthorized Missing, invalid, expired or revoked token
403 forbidden Missing permission, or tenant disabled
404 not_found Object (or tenant) not found or not visible to you
409 conflict An object with the same unique value already exists
409 in_use The object is still referenced by another, or a referenced object is missing
409 overlap The value overlaps an existing object (for example a network device address range)
429 locked Too many failed sign-in or token attempts
500 internal Unexpected server error; the message is not shown

Some modules add their own codes (for example pki_unavailable or upstream_error); their pages list them. Base your error handling on the HTTP status and code, not on the message text.

Airgate does not apply a general request rate limit to the REST API. These limits apply:

  • Sign-in and token issue: 10 failed attempts per account or client ID lock it for 15 minutes after the last failure.
  • Specific endpoints that do expensive work or face the public (policy simulation, guest and BYOD portals, SCEP and others) have their own limits, documented on their pages. They answer 429.

Write automation that backs off and retries on 429 and 5xx answers.

Every change made through the API is written to the tenant’s audit log with the principal (administrator or API client) as the actor, the source IP address, the object and the changed fields. See Settings › Audit log and GET /audit.

Page Covers
Administration Sign-in, administrators, API clients, tenants, tenant settings, audit log, appliance software update and backups
Console single sign-on SAML and OpenID Connect identity providers for console sign-in
Access policy Policy dictionary, condition validation, Test access simulation
Policy administration Access policies, enforcement, authentication methods and profiles
Identity and directories Directories, local users, roles
Endpoints Devices, MAC lists, device attributes
Device profiling Device types and profiling rules
Network devices Switches, access points, controllers, device groups
Site connector (edge) Site connectors and the connector API
RADIUS RADIUS service settings and state
Change of Authorization Reauthenticate, disconnect, bounce
TACACS+ Device administration
Guest access Guest accounts, Wi-Fi passes, guest portals
Certificates and onboarding Certificate authorities, certificates, SCEP, server certificates
BYOD BYOD portals and devices
Monitoring and reports Sign-in log, sessions, events, alerts, reports
Logs and packet capture Logs, debug logging, packet capture
Webhooks and log export Webhooks, device sources, syslog and SIEM export
© 2026 Airowire Networks Pvt. Ltd. Airgate is a product of Airowire.Product · Release notes · Security