Skip to content

Administration API

The administration API covers who can use Airgate and how the platform is run: sign-in and tokens, administrators, API clients, the tenant’s own settings and audit log, and, for platform administrators, tenants, appliance software updates and backups. It backs Settings › Administrators, Settings › API keys, Settings › General, Settings › Audit log, Settings › Tenants, Settings › Software update and Settings › Backups.

Group Base path Permission
Sign-in and tokens /api/v1/auth/…, /api/v1/oauth/token None to sign in; any valid token for the rest
Administrators, API clients, tenant, audit /api/v1/t/{tenant} admin:read to read, admin:write to change
Tenants, platform audit, appliance /api/v1/platform platform:admin

{tenant} is the tenant slug or ID. See the REST API overview for tokens, list envelopes and errors. Single sign-on providers are on the console single sign-on API page.

Method Path Permission
POST /api/v1/auth/login none
POST /api/v1/oauth/token none (client credentials)
GET /api/v1/auth/me any token
POST /api/v1/auth/logout any token
POST /api/v1/auth/password any administrator token
GET /api/v1/auth/roles any token
GET /admin-users admin:read
POST /admin-users admin:write
PUT /admin-users/{id} admin:write
DELETE /admin-users/{id} admin:write
GET /api-clients admin:read
POST /api-clients admin:write
PUT /api-clients/{id} admin:write
DELETE /api-clients/{id} admin:write
GET /tenant any token of the tenant
PUT /tenant/settings admin:write
GET /audit admin:read
GET, POST /api/v1/platform/tenants platform:admin
PUT, DELETE /api/v1/platform/tenants/{id} platform:admin
POST /api/v1/platform/tenants/{id}/admins platform:admin
GET /api/v1/platform/audit platform:admin
various /api/v1/platform/appliance/… platform:admin

Permission: none

Signs an administrator in with a password and returns an 8-hour token.

Field Type Meaning
email string The administrator’s email. A bare name without @ also works when exactly one administrator’s email starts with it (alice for alice@contoso.com); an exact email always wins
password string The password
Terminal window
curl -s -X POST "$AIRGATE/api/v1/auth/login" -H "Content-Type: application/json" \
-d '{"email": "alice@contoso.com", "password": "…"}'
{
"token": "eyJhbGciOi…",
"expires_at": "2026-11-19T16:30:00Z",
"principal": { "kind": "user", "name": "Alice", "email": "alice@contoso.com", "role": "tenant_admin", "…": "…" }
}

A wrong email or password answers 401 unauthorized (invalid email or password), the same for both. Ten failures for one account answer 429 locked until 15 minutes after the last failure. A disabled account or tenant cannot sign in.

Permission: none (client credentials)

Issues a 1-hour token to an API client. See Authentication for the request, response and errors.

Permission: any valid token

Returns the signed-in principal.

{
"kind": "client",
"id": "5b1e…",
"name": "Inventory sync",
"email": "",
"role": "network_admin",
"tenant_id": "9eac…",
"platform": false,
"permissions": ["policy:read", "policy:write", "identity:read", "…"],
"tenants": [{"id": "9eac…", "slug": "contoso", "name": "Contoso"}]
}

kind is user (administrator) or client (API client). tenants lists the tenants the principal can open: its own tenant, or every enabled tenant for a platform administrator.

Permission: any valid token

Revokes every token issued to this principal so far (not only the one in the request). Answers 204.

Permission: any administrator token (API clients get 400)

Changes the caller’s own password. Answers 204; every session of the account, including the current one, is signed out.

Field Type Meaning
current_password string The current password; a wrong one answers 403
new_password string At least 8 characters

Permission: any valid token

Returns the role catalogue: an object from role name to its list of permissions. See Permissions and roles.

Administrators of the current tenant. Platform administrators are not listed here.

Permission: admin:read

Returns every administrator of the tenant, ordered by email, in the list envelope.

{"items": [{
"id": "1c7d…", "tenant_id": "9eac…", "email": "alice@contoso.com", "name": "Alice",
"role": "tenant_admin", "enabled": true, "last_login_at": "2026-11-18T09:12:44Z",
"created_at": "2026-10-02T11:00:00Z", "auth_source": "local", "sso_provider": ""
}], "total": 1}

auth_source is local (password) or sso (created by a single sign-on provider, whose name is in sso_provider).

Permission: admin:write

Field Type Meaning
email string Required; stored in lower case; unique across the platform
name string Display name
role string Required. tenant_admin, network_admin, helpdesk, guest_operator or read_only. You can only grant a role whose permissions you hold
password string Required, at least 8 characters
enabled boolean Default true
Terminal window
curl -s -X POST "$AIRGATE/api/v1/t/$TENANT/admin-users" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"email": "bob@contoso.com", "name": "Bob", "role": "helpdesk", "password": "…"}'

Answers 201 with the administrator. An email that already exists answers 409 conflict.

Permission: admin:write

Same fields as create; absent or empty fields keep their value (email cannot be changed). Changing the role or password, or disabling the account, signs it out everywhere. You cannot disable yourself. Answers 200 with the administrator.

Permission: admin:write

Deletes the administrator. You cannot delete yourself. Answers 204.

API clients are the credentials behind Settings › API keys.

Permission: admin:read

{"items": [{
"id": "5b1e…", "client_id": "nac_3Jq0x8b2Lk", "name": "Inventory sync",
"description": "CMDB import", "role": "network_admin", "enabled": true,
"last_used_at": "2026-11-19T07:00:02Z", "created_at": "2026-11-01T10:00:00Z"
}], "total": 1}

last_used_at is when the client last received a token. Secrets are never returned.

Permission: admin:write

Field Type Meaning
name string Required
client_id string Optional; default nac_ followed by a random string. Unique across the platform
description string Free text
role string Required; any role except platform_admin, and only one whose permissions you hold
enabled boolean Default true
Terminal window
curl -s -X POST "$AIRGATE/api/v1/t/$TENANT/api-clients" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"name": "Inventory sync", "role": "read_only"}'
{"client": {"id": "5b1e…", "client_id": "nac_3Jq0x8b2Lk", "name": "Inventory sync", "role": "read_only", "enabled": true, "…": "…"},
"client_secret": "q2Vt…"}

Permission: admin:write

Changes name, description, role or enabled (absent or empty fields keep their value). Send "rotate_secret": true to issue a new secret: the response then carries client_secret again. Rotating the secret, changing the role or disabling the client revokes every token already issued to it. Answers 200 with {"client": {…}}.

Permission: admin:write

Deletes the client; its tokens stop working. Answers 204.

Permission: any token of the tenant

Returns the tenant: id, slug, name, enabled, settings, created_at. With admin:read you get the full settings document (values whose key looks like a secret, such as password, token or api_key, are shown as ********); without it, settings holds only timezone.

Permission: admin:write

Merges top-level keys into the tenant’s settings. A key set to null is removed; a value of "********" keeps the stored value. Answers 200 with the tenant.

Key Meaning
timezone The tenant’s IANA time zone (for example Europe/London); used for time-of-day conditions and reports. An unknown zone answers 400
other keys Module settings documented on their pages, for example the profiler’s retention settings on the device profiling API
Terminal window
curl -s -X PUT "$AIRGATE/api/v1/t/$TENANT/tenant/settings" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"timezone": "Asia/Kolkata"}'

Permission: admin:read

Returns the tenant’s audit records, newest first, in the list envelope.

Parameter Meaning
q Substring of the actor name, object name or action
object_type Exact object type, for example admin_user, api_client, nad, tenant
action Exact action, for example create, update, delete, login
actor Substring of the actor name
from, to RFC 3339 time range
limit, offset Paging (default 50, at most 1000)
Terminal window
curl -s "$AIRGATE/api/v1/t/$TENANT/audit?object_type=api_client&from=2026-11-01T00:00:00Z" \
-H "Authorization: Bearer $TOKEN"
{"items": [{
"id": 9031, "tenant_id": "9eac…", "at": "2026-11-18T10:02:11Z",
"actor_kind": "user", "actor_id": "1c7d…", "actor_name": "alice@contoso.com",
"action": "update", "object_type": "api_client", "object_id": "5b1e…", "object_name": "nac_3Jq0x8b2Lk",
"details": {"rotated": true}, "source_ip": "203.0.113.10"
}], "total": 1}

actor_kind is user, client or system. Details never contain secrets.

Permission: platform:admin

Every tenant, ordered by name, with full (unmasked) settings.

Permission: platform:admin

Field Type Meaning
slug string Required; 2 to 63 characters of a-z, 0-9 and -, starting with a letter or digit
name string Required
settings object Optional initial settings

Creates the tenant with its default content and answers 201. A slug in use answers 409.

Permission: platform:admin

Changes name, enabled or replaces settings. Disabling a tenant signs out its administrators and API clients at once and refuses their requests. Answers 200.

Permission: platform:admin

Deletes the tenant and everything in it. Answers 204.

Permission: platform:admin

Creates a Tenant Administrator in the tenant: email, name, password (at least 8 characters). Answers 201 with {"id": "…"}.

Permission: platform:admin

The platform audit log (tenant lifecycle, platform administrators). Same parameters and records as GET /audit; add tenant_id=<uuid> to read one tenant’s records.

These routes exist on every installation. On an appliance they drive the update agent; elsewhere GET /appliance reports the running version with "agent": null and the other routes answer an error. See Software updates for the procedure.

Method Path (under /api/v1/platform) Purpose
GET /appliance {version, agent, agent_error}: installed and previous version, signature mode, running operation, history
GET /appliance/log The last operation’s log, as text
POST /appliance/uploads Start an upload; answers {id}
PUT /appliance/uploads/{id}?offset=N Append a chunk (raw body, at most 64 MiB; the console sends 8 MiB). offset is the number of bytes sent so far
POST /appliance/uploads/{id}/verify Check the signature and the SHA-256 of every file; answers the manifest summary (version, created, size, images, current, notes)
POST /appliance/uploads/{id}/apply Install the verified update; body {"force": true} reinstalls the running version. Answers 202; follow progress with GET /appliance
DELETE /appliance/uploads/{id} Discard an upload
POST /appliance/rollback Return to the previous version. Answers 202

All routes need platform:admin. Verify, apply and rollback are audited.

See Backups and restore for what a backup contains.

Method Path (under /api/v1/platform) Purpose
GET /appliance/backups Settings (passphrase shown only as set or not), backup files, history
GET /appliance/backups/log The last backup or restore log
POST /appliance/backups Back up now
PUT /appliance/backups/settings Schedule (schedule.enabled, schedule.time HH:MM), keep (1 to 365), passphrase (at least 12 characters), backup server (SFTP) settings
POST /appliance/backups/remote/test Connect to the SFTP server, check the directory is writable, pin the server key
GET /appliance/backups/files/{name} Download a backup file
DELETE /appliance/backups/files/{name} Delete a backup file
POST /appliance/backups/files/{name}/check Body {"passphrase"} (empty = the stored one); describes the backup: appliance, date, version, console address, or why it cannot be restored here
POST /appliance/backups/files/{name}/restore Body {"passphrase", "force", "confirm": "RESTORE"}; restores a backup kept on the appliance. Answers 202
POST /appliance/backups/uploads Start uploading a backup file
PUT /appliance/backups/uploads/{id}?offset=N Append a chunk
POST /appliance/backups/uploads/{id}/check Describe an uploaded backup
POST /appliance/backups/uploads/{id}/restore Same body; restores an uploaded backup. Answers 202
DELETE /appliance/backups/uploads/{id} Discard an upload

All routes need platform:admin. Backing up, changing settings, deleting and restoring are audited.

Appliance Active Directory join (platform)

Section titled “Appliance Active Directory join (platform)”
Method Path (under /api/v1/platform) Purpose
GET /appliance/ad Join state
POST /appliance/ad/test Test the join
POST /appliance/ad/join Join the appliance to the domain (for PEAP-MSCHAPv2 against Active Directory)
POST /appliance/ad/leave Leave the domain

All routes need platform:admin. Join and leave are audited. See Active Directory with PEAP.

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