Skip to content

Identity and directories API

The identity API manages directories (authentication sources) and the local user repository: create and test directories, look up a user, and create, import and export local users. It backs the console pages Access › Directories and Access › Local users.

All routes are relative to /api/v1/t/{tenant}, where {tenant} is the tenant slug or ID. Every route needs a bearer token (see API overview).

Permission Grants
policy:read List and read directories and directory types; run a connection test of a saved directory.
policy:write Create, change, delete directories; test an unsaved configuration; look up a user.
identity:read List, read and export local users; read import jobs.
identity:write Create, change, delete and import local users; set passwords.

Lists use the standard envelope {"items": [...], "total": N} with ?q=&limit=&offset=. Every change is written to the audit log (object types auth_source, local_user). Secrets never appear in responses, audit details or logs.

Method Path Permission
GET /auth-source-types policy:read
GET /auth-sources policy:read
POST /auth-sources policy:write
POST /auth-sources/test policy:write
GET /auth-sources/{id} policy:read
PUT /auth-sources/{id} policy:write
PATCH /auth-sources/{id} policy:write
DELETE /auth-sources/{id} policy:write
POST /auth-sources/{id}/test policy:read
POST /auth-sources/{id}/lookup policy:write
GET /local-users identity:read
POST /local-users identity:write
POST /local-users/import identity:write
POST /local-users/upsert identity:write
GET /local-users/import-jobs identity:read
GET /local-users/import-jobs/{id} identity:read
GET /local-users/export.csv identity:read
GET /local-users/{id} identity:read
PUT /local-users/{id} identity:write
DELETE /local-users/{id} identity:write
POST /local-users/{id}/password identity:write
{
"id": "5b0d…", "tenant_id": "9c1e…",
"name": "Corp AD", "description": "", "type": "AD",
"use_for_authorization": true,
"authorization_source_ids": [],
"config": {
"host_name": "dc1.contoso.com", "connection_port": 389, "connection_security": "StartTLS",
"verify_server_certificate": true, "bind_DN": "svc-airgate@contoso.com", "bind_password": "********",
"base_DN": "DC=contoso,DC=com", "search_scope": "SubTree_Search", "bind_user": true,
"nested_groups": false, "max_connections": 8, "timeout": 5, "role_aliases": ["Department"]
},
"filters": [
{"name": "Authentication", "enabled": true,
"query": "(&(objectClass=user)(|(sAMAccountName=%{Authentication:Username})(userPrincipalName=%{Authentication:Username})))",
"attributes": {"dn": "UserDN", "memberOf": "memberOf", "department": "Department", "mail": "Email", "displayName": "Name"}},
{"name": "Group", "enabled": true, "query": "(distinguishedName=%{memberOf})", "attributes": {"cn": "Groups"}}
],
"backup_servers": [{"host_name": "dc2.contoso.com"}],
"cache_timeout_sec": 36000,
"system": false,
"enabled": true,
"driver_registered": true,
"created_at": "2026-10-29T08:00:00Z", "updated_at": "2026-10-29T08:00:00Z"
}
Field Meaning
type Directory type (see Directory types).
use_for_authorization Fetch attributes from this directory after authentication.
authorization_source_ids Further directories queried for attributes. On write, authorization_source_names (names) is accepted instead.
config Type-specific settings. Replaced as a whole when sent.
filters Searches that fetch attributes. query is a template with %{Namespace:Name} variables; attributes maps directory attribute → alias. The filter named Authentication is the user search. When omitted on create, the type’s default filters apply.
backup_servers Failover servers for types that support them.
cache_timeout_sec Attribute cache lifetime, 0–604800 seconds.
system Built-in directory ([Local User Repository], [Endpoints Repository], [Guest User Repository], [Insight Repository], [Time Source]). Built-in directories cannot be renamed, re-typed, deleted or disabled.
enabled A disabled directory stays referenced by access policies but is skipped at sign-in.

Secrets. Passwords, client secrets, API tokens, private keys and every value of secret_headers and secret_params are stored sealed and returned as "********". Sending "********" keeps the stored value; "" clears it.

{"error": "connection target changed (https://collector.contoso.com:443): stored secrets are never sent to a new or less verified server — enter config.login_password again (or clear it)",
"code": "secret_required",
"fields": [{"scope": "config", "key": "login_password", "path": "config.login_password"},
{"scope": "backup_servers", "index": 1, "key": "secret", "path": "backup_servers[1].secret"}]}

Permission: policy:read

Lists directory types with their capabilities, configuration schema (for building forms) and default filters.

{"items": [
{"type": "AD", "label": "Active Directory", "description": "…", "system": false, "registered": true,
"capabilities": {"lookup": true, "verify": true, "credentials": false, "attributes": true, "mac": false},
"filter_language": "ldap", "backup_servers": true,
"fields": [{"name": "host_name", "label": "Hostname", "type": "string", "required": true},
{"name": "bind_password", "label": "Bind password", "type": "secret", "required": true}],
"default_filters": ["…"]}],
"total": 15}

Field type is one of string, text, int, bool, secret, enum, list, map, secret_map.

Permission: policy:read

Query parameter Type Meaning
q string Name or description.
type string Directory type.
enabled boolean Filter by state.
Terminal window
curl -s "$AIRGATE/api/v1/t/$TENANT/auth-sources?type=AD" -H "Authorization: Bearer $TOKEN"

Permission: policy:write

Body: the directory object (id, system and timestamps are ignored). Response 201. Validation errors (unknown type, missing required configuration, invalid filters, unknown authorization sources, self-reference) return 400; a duplicate name returns 409.

Terminal window
curl -s -X POST "$AIRGATE/api/v1/t/$TENANT/auth-sources" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"name": "Corp AD", "type": "AD",
"config": {"host_name": "dc1.contoso.com", "connection_port": 636, "connection_security": "LDAP_SSL",
"bind_DN": "svc-airgate@contoso.com", "bind_password": "…", "base_DN": "DC=contoso,DC=com"}}'

Permission: policy:read. Response 200: the directory object (secrets masked).

Permission: policy:write

Every field is optional; omitted fields are unchanged. Response 200. Returns 400 secret_required as described above.

Permission: policy:write

Only {"enabled": true | false}. Recorded in the audit log as enable / disable. Built-in directories cannot be disabled (400). Response 200.

Permission: policy:write

Response 204. Built-in directories return 400. A directory still referenced returns 409:

{"error": "auth source is still referenced", "code": "in_use",
"referrers": [{"type": "service", "id": "…", "name": "Corp-WiFi 802.1X"}]}

POST /auth-sources/{id}/test · POST /auth-sources/test

Section titled “POST /auth-sources/{id}/test · POST /auth-sources/test”

Permission: policy:read (saved directory), policy:write (unsaved configuration)

Tests the connection. The first form takes no body; the second takes a directory object (with id of a saved directory, masked secrets are taken from it, subject to the secret_required rule).

{"ok": false, "error": "service account bind failed: LDAP Result Code 49 …", "latency_ms": 41}

What is tested: LDAP / AD service bind and base DN read; SQL SELECT 1; HTTP GET of the base URL; RADIUS Status-Server (or a probe Access-Request); Entra ID token and a Graph user query; Okta API; MAC lists exist.

Permission: policy:write

Field Type Meaning
username string User to look up.
password string Optional. When given, the password is verified.

Runs the lookup (or verification) and the authorization chain, and works on disabled directories so you can try them before enabling. Always returns 200; failures are in error and error_code (user_not_found, bad_password, disabled, expired, unsupported, unavailable).

{"found": true, "verified": false, "latency_ms": 12,
"identity": {"username": "alice", "source_name": "[Local User Repository]", "source_type": "Local",
"enabled": true, "role": "[Employee]", "attributes": {"Role_Name": ["[Employee]"]},
"has_nt_hash": true, "has_cleartext": false, "has_password_with_header": false},
"authorization": {"Authorization": {"Sources": ["[Local User Repository]"]},
"Authorization:[Local User Repository]": {"Role_Name": ["[Employee]"], "Email": ["alice@contoso.com"]}}}
type Required configuration Notes
Local none The tenant’s local users.
AD host_name, bind_DN, bind_password, base_DN connection_port (389/636), connection_security (None, StartTLS, LDAP_SSL), verify_server_certificate, ca_certificate, search_scope, bind_user, net_BIOS_domain_name, nested_groups, max_connections. PEAP-MSCHAPv2 against AD needs a domain-joined site connector (see Site connector).
Ldap as AD (bind optional) Adds password_attribute, password_type, password_header.
Sql odbc_type (PostgreSQL, MySQL, MariaDB, MSSQL), server_name, database_name, login_user_name port, login_password, password_type, ssl_mode (disable, prefer, require, verify-full).
HTTP base_URL auth_type (None, Basic, Bearer, Header, SSWS), headers, secret_headers, secret_params, lookup_url, verify_url and related fields. Credentials go only to the configured origins.
RadiusServer, TokenServer server_name, secret port, nas_identifier, nas_ip_address, retries, require_message_authenticator. Password check only (PAP proxy).
EntraID tenantID, clientID secretType (secret or certificate), clientSecret or client_certificate + client_certificate_key, ropc_enabled, nested_groups.
Okta base_URL authorization_token (API token), allow_mfa_required.
GoogleWorkspace domain, client_certificate, client_certificate_key Google Secure LDAP with the LDAP client certificate. PAP, EAP-TTLS/PAP and EAP-TLS; no MS-CHAP.
SHL static_host_lists MAC / IP list membership.
Time none Time attributes only.

All external types also accept timeout (seconds, default 5) and role_aliases (aliases whose values become roles). Connections to directory servers follow the platform egress policy (see Security hardening).

{"id": "…", "tenant_id": "…", "username": "alice", "display_name": "Alice Example", "email": "alice@contoso.com",
"role_id": "…", "role": "[Employee]", "enabled": true, "change_pwd_next_login": false,
"expires_at": "2027-01-01T00:00:00Z", "attributes": {"Phone": "123", "Group": ["a", "b"]},
"has_password": true, "has_nt_hash": true, "has_reversible_password": false, "credentials_imported": false,
"password_updated_at": "…", "created_at": "…", "updated_at": "…"}

User names are case-insensitive and unique in the tenant. Passwords are stored as a bcrypt hash and a sealed NT hash (for MSCHAPv2 / PEAP); a sealed reversible copy is kept only when the tenant setting store_reversible_passwords is on (CHAP / EAP-MD5). Passwords must follow the tenant password policy (min_length 8, max_length 128, optional mixed case, digit, special character, no user name, expiry_days) and are limited to 72 bytes.

Permission: identity:read

Query parameter Type Meaning
q string User name, display name or email.
role string Role name or ID.
enabled boolean Filter by state.
sort string username, -username, created_at, -created_at, display_name or -updated_at.
limit, offset integer Paging.

Permission: identity:write

Field Type Meaning
username string Required.
password string Password (policy-checked).
display_name, email string Profile.
role / role_id string Role name or ID.
enabled boolean Default true.
change_pwd_next_login boolean Flag available to policy.
expires_at time RFC 3339, YYYY-MM-DD HH:MM:SS, date or epoch.
attributes object Custom attributes (strings or lists).
Terminal window
curl -s -X POST "$AIRGATE/api/v1/t/$TENANT/local-users" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"username": "alice", "password": "…", "display_name": "Alice Example",
"email": "alice@contoso.com", "role": "[Employee]"}'

Response 201: the local user. A duplicate user name returns 409.

GET /local-users/{id} · PUT /local-users/{id} · DELETE /local-users/{id}

Section titled “GET /local-users/{id} · PUT /local-users/{id} · DELETE /local-users/{id}”

Permission: identity:read (GET), identity:write (PUT, DELETE)

PUT accepts any subset of the create fields; a non-empty password (not "********") also resets the credential; expires_at: null clears the expiry. Responses: 200 (GET, PUT), 204 (DELETE).

Permission: identity:write

{"password": "…", "change_pwd_next_login": false}. Response 200: the local user.

Permission: identity:write

Imports users from CSV: the file in the multipart field file, or the CSV as the request body. Limits: 32 MiB and 200 000 rows. Options as query parameters or multipart form fields:

Option Values Meaning
dry_run true / false Validate only.
mode upsert (default) or create Merge into existing users, or only create.
credentials replace (default) or keep_changed keep_changed replaces credentials only while the stored ones are still the imported ones, so passwords changed since the last import are kept. keep_changed_credentials=true is an alias.
default_role role name Role for rows without one.
async auto (default), true, false Run as a background job. With auto, imports whose password hashing would take more than about 30 seconds become jobs.

Columns (case-insensitive; aliases in brackets): username (user_id, login, required), password, display_name (name, full_name), email, role (role_name), enabled, change_pwd_next_login, expires_at (expire_time), nt_hash (password_ntlm_hash), password_hash (legacy_hash) with legacy_hash_format. Any other column (or attr:<name>) becomes a custom attribute. New users need a password, NT hash or supported legacy hash (bcrypt, PBKDF2, {SSHA} and similar); hashes Airgate cannot verify are row errors.

Terminal window
curl -s -X POST "$AIRGATE/api/v1/t/$TENANT/local-users/import?mode=upsert&credentials=keep_changed" \
-H "Authorization: Bearer $TOKEN" -F "file=@users.csv"

Response 200 (report) or 202 (job object):

{"dry_run": false, "total": 8, "created": 3, "updated": 1, "skipped": 0, "credentials_kept": 0,
"errors": [{"line": 6, "username": "badrole", "error": "unknown role \"NoSuchRole\""}]}

All valid rows are written in one transaction: either every valid row is written or none. At most 2 import jobs run per tenant; a further one returns 409 with code import_running.

Permission: identity:write

The JSON form of the import, for scripts and migrations. Same options and rules; at most 10 000 users (8 MiB) per request.

{"mode": "upsert", "credentials": "keep_changed", "dry_run": false, "default_role": "[Employee]", "async": "auto",
"users": [
{"username": "alice", "password": "…", "display_name": "Alice", "email": "alice@contoso.com",
"role": "[Employee]", "enabled": true, "expires_at": "2027-01-01T00:00:00Z", "attributes": {"Department": "Eng"}},
{"username": "bob", "nt_hash": "8846f7eaee8fb117ad06bdd830b7586c"}]}

Errors carry the 1-based position of the user as line. Response: as POST /local-users/import.

GET /local-users/import-jobs · GET /local-users/import-jobs/{id}

Section titled “GET /local-users/import-jobs · GET /local-users/import-jobs/{id}”

Permission: identity:read

Background import jobs, newest first (the list omits report). Finished jobs are deleted after 30 days.

{"id": "…", "status": "running", "kind": "csv", "rows": 9800,
"created_by": "admin@contoso.com", "created_at": "…", "finished_at": null,
"report": null, "error": ""}

status is running, done or failed; kind is csv or json.

Permission: identity:read

CSV with username,display_name,email,role,enabled,change_pwd_next_login,expires_at and one column per custom attribute. Never contains credentials.

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