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.
Base path and permissions
Section titled “Base path and permissions”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.
Route summary
Section titled “Route summary”| 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 |
Directories
Section titled “Directories”Directory object
Section titled “Directory object”{ "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"}]}GET /auth-source-types
Section titled “GET /auth-source-types”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.
GET /auth-sources
Section titled “GET /auth-sources”Permission: policy:read
| Query parameter | Type | Meaning |
|---|---|---|
q |
string | Name or description. |
type |
string | Directory type. |
enabled |
boolean | Filter by state. |
curl -s "$AIRGATE/api/v1/t/$TENANT/auth-sources?type=AD" -H "Authorization: Bearer $TOKEN"POST /auth-sources
Section titled “POST /auth-sources”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.
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"}}'GET /auth-sources/{id}
Section titled “GET /auth-sources/{id}”Permission: policy:read. Response 200: the directory object (secrets masked).
PUT /auth-sources/{id}
Section titled “PUT /auth-sources/{id}”Permission: policy:write
Every field is optional; omitted fields are unchanged. Response 200. Returns 400 secret_required as described above.
PATCH /auth-sources/{id}
Section titled “PATCH /auth-sources/{id}”Permission: policy:write
Only {"enabled": true | false}. Recorded in the audit log as enable / disable. Built-in directories cannot be disabled (400). Response 200.
DELETE /auth-sources/{id}
Section titled “DELETE /auth-sources/{id}”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.
POST /auth-sources/{id}/lookup
Section titled “POST /auth-sources/{id}/lookup”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"]}}}Directory types
Section titled “Directory types”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).
Local users
Section titled “Local users”Local user object
Section titled “Local user object”{"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.
GET /local-users
Section titled “GET /local-users”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. |
POST /local-users
Section titled “POST /local-users”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). |
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).
POST /local-users/{id}/password
Section titled “POST /local-users/{id}/password”Permission: identity:write
{"password": "…", "change_pwd_next_login": false}. Response 200: the local user.
POST /local-users/import
Section titled “POST /local-users/import”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.
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.
POST /local-users/upsert
Section titled “POST /local-users/upsert”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.
GET /local-users/export.csv
Section titled “GET /local-users/export.csv”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.