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.
Base path and permissions
Section titled “Base path and permissions”| 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 |
Sign-in and tokens
Section titled “Sign-in and tokens”POST /api/v1/auth/login
Section titled “POST /api/v1/auth/login”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 |
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.
POST /api/v1/oauth/token
Section titled “POST /api/v1/oauth/token”Permission: none (client credentials)
Issues a 1-hour token to an API client. See Authentication for the request, response and errors.
GET /api/v1/auth/me
Section titled “GET /api/v1/auth/me”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.
POST /api/v1/auth/logout
Section titled “POST /api/v1/auth/logout”Permission: any valid token
Revokes every token issued to this principal so far (not only the one in the request). Answers 204.
POST /api/v1/auth/password
Section titled “POST /api/v1/auth/password”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 |
GET /api/v1/auth/roles
Section titled “GET /api/v1/auth/roles”Permission: any valid token
Returns the role catalogue: an object from role name to its list of permissions. See Permissions and roles.
Administrators
Section titled “Administrators”Administrators of the current tenant. Platform administrators are not listed here.
GET /admin-users
Section titled “GET /admin-users”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).
POST /admin-users
Section titled “POST /admin-users”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 |
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.
PUT /admin-users/{id}
Section titled “PUT /admin-users/{id}”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.
DELETE /admin-users/{id}
Section titled “DELETE /admin-users/{id}”Permission: admin:write
Deletes the administrator. You cannot delete yourself. Answers 204.
API clients
Section titled “API clients”API clients are the credentials behind Settings › API keys.
GET /api-clients
Section titled “GET /api-clients”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.
POST /api-clients
Section titled “POST /api-clients”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 |
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…"}PUT /api-clients/{id}
Section titled “PUT /api-clients/{id}”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": {…}}.
DELETE /api-clients/{id}
Section titled “DELETE /api-clients/{id}”Permission: admin:write
Deletes the client; its tokens stop working. Answers 204.
Tenant and tenant settings
Section titled “Tenant and tenant settings”GET /tenant
Section titled “GET /tenant”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.
PUT /tenant/settings
Section titled “PUT /tenant/settings”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 |
curl -s -X PUT "$AIRGATE/api/v1/t/$TENANT/tenant/settings" \ -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \ -d '{"timezone": "Asia/Kolkata"}'Audit log
Section titled “Audit log”GET /audit
Section titled “GET /audit”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) |
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.
Tenants (platform)
Section titled “Tenants (platform)”GET /api/v1/platform/tenants
Section titled “GET /api/v1/platform/tenants”Permission: platform:admin
Every tenant, ordered by name, with full (unmasked) settings.
POST /api/v1/platform/tenants
Section titled “POST /api/v1/platform/tenants”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.
PUT /api/v1/platform/tenants/{id}
Section titled “PUT /api/v1/platform/tenants/{id}”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.
DELETE /api/v1/platform/tenants/{id}
Section titled “DELETE /api/v1/platform/tenants/{id}”Permission: platform:admin
Deletes the tenant and everything in it. Answers 204.
POST /api/v1/platform/tenants/{id}/admins
Section titled “POST /api/v1/platform/tenants/{id}/admins”Permission: platform:admin
Creates a Tenant Administrator in the tenant: email, name, password (at least 8 characters). Answers 201 with {"id": "…"}.
GET /api/v1/platform/audit
Section titled “GET /api/v1/platform/audit”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.
Appliance software update (platform)
Section titled “Appliance software update (platform)”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.
Appliance backups (platform)
Section titled “Appliance backups (platform)”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.