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.
Base URL
Section titled “Base URL”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.
Authentication
Section titled “Authentication”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.
Step 1: create an API client
Section titled “Step 1: create an API client”- In the console, go to Settings › API keys.
- Select Create API client (you need the
admin:writepermission, for example the Tenant Administrator role). - 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.
- 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.
Step 2: get an access token
Section titled “Step 2: get an access token”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.
export AIRGATE=https://airgate.contoso.comexport CLIENT_ID=nac_xxxxxxxxxxxxexport 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.
Step 3: call the API
Section titled “Step 3: call the API”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"Administrator sign-in
Section titled “Administrator sign-in”People sign in with POST /api/v1/auth/login:
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.
Revoking tokens
Section titled “Revoking tokens”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.
Permissions and roles
Section titled “Permissions and roles”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>.
Requests
Section titled “Requests”- 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_atand other read-only fields). - On
PUTupdates, most modules treat an absent field as “keep the current value”; the module pages say where aPUTreplaces 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.
Lists, paging and filtering
Section titled “Lists, paging and filtering”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.
# 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
Section titled “Errors”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.
Rate limits
Section titled “Rate limits”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.
Auditing
Section titled “Auditing”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.
API reference by module
Section titled “API reference by module”| 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 |