Use the Atlaso API¶

Managed LDAP organization responses include vcenter_groups_base_dn, the separate groupOfUniqueNames/uniqueMember search base created by global LDAP Apply. The existing groups_base_dn remains the VCF Automation groupOfNames/member base. Existing paths, operation IDs, authorization and request shapes remain unchanged. See Managed LDAP compatibility groups.

DHCP pool verification uses GET /api/v1/dhcp/scopes/{scope_id}/verification (read:dhcp) and POST /api/v1/dhcp/scopes/{scope_id}/verification (write:dhcp). POST queues a bounded, report-only worker task and returns 202 with its task ID; unavailable applied identity or admission returns 409. It accepts a managed IPv4 pool ID rather than an arbitrary network. Reports distinguish occupancy, mismatches, nonresponse and unknown evidence and do not change leases or runtime configuration. The additive DHCP settings field check_ip_availability controls native daemon-wide IPv4 candidate checking after global Appliance Apply; omission preserves an existing explicit opt-out. See DHCP for limits, scheduling, cancellation and evidence meaning.

Atlaso publishes its supported REST contract under /api/v1. Use the interactive Swagger UI at /api/docs, the alternative ReDoc view at /api/redoc, or the machine-readable OpenAPI 3.1 document at /openapi.json. The schema contains only versioned /api/v1 operations; browser pages and service-specific protocol routes remain supported but are documented in their service guides instead of Swagger.

The authenticated browser application is rooted at /ui/management, and app-owned public pages are rooted at /ui/public. Those presentation namespaces do not change API URLs or make management APIs available on Public Services listeners. See Public Services for the listener and compatibility contract.

Create and protect an API token¶

1. Sign in to the management UI and open Authentication > API Tokens.
2. Create a token with a clear purpose and only the scopes required by the client. The final review shows the current configured maximum lifetime and the absolute expiration that will be submitted.
3. Copy the token when it is shown. Atlaso displays the secret once and cannot recover it later.
4. In /api/docs, select Authorize, paste the token value, and authorize the bearer scheme.
5. Revoke the token when its client is retired or its value may have been exposed. Create a replacement instead of trying to recover or reuse the old secret.

Token issuance saves the token and its creation audit event in one transaction for both the API and management UI. If that transaction fails, neither record is saved and no token secret is returned.

Treat bearer tokens like passwords. Do not put them in command history, source files, screenshots, issue reports, authenticated URLs, or shared logs. Prefer a secret manager for automation and an environment variable for short-lived interactive work.

The maximum lifetime is configured under Appliance Settings > Authentication lifetimes. It defaults to 90 days and accepts 1 through 365 days. POST /api/v1/auth/login and POST /api/v1/api-tokens use the current policy at the instant of issuance: omit expires_at to use the maximum, or provide a timezone-aware timestamp that is in the future and no later than that boundary. Naive timestamps, past timestamps, and values beyond the maximum return 422. Changing the policy affects only later issuance; Atlaso never extends, shortens, or revives an existing token.

Call the API safely¶

The examples below use the RFC 1918 lab address 192.168.50.10 and read the token from the environment. Replace the address with the appliance management address; do not replace the token variable with a literal secret.

export ATLASO_TOKEN="<read securely from your secret manager>"
curl --fail-with-body --silent --show-error \
  --header "Authorization: Bearer ${ATLASO_TOKEN}" \
  --header "Accept: application/json" \
  https://192.168.50.10/api/v1/dashboard

$headers = @{
    Authorization = "Bearer $env:ATLASO_TOKEN"
    Accept = "application/json"
}
Invoke-RestMethod -Uri "https://192.168.50.10/api/v1/dashboard" -Headers $headers

Use a certificate trusted by the client. Do not disable TLS verification in saved automation. Examples that create or change resources should use RFC 1918 lab addresses such as 192.168.50.0/24 and be reviewed against the operation's documented authorization and apply behavior before execution.

Configure management UI exposure on access interfaces¶

PhysicalInterfaceResponse and VlanCreate/VlanResponse include access_management_ui_enabled. Set it only on an access-role, access-mode physical interface or an access-role VLAN. The switch exposes the authenticated /ui/management browser plane without changing that interface's access routing or public-service eligibility. A management-role physical interface ignores the switch because it exposes management inherently. Physical-interface mutation rejects a desired configuration that would leave no complete management UI candidate. A complete flagged access replacement is saved as desired state and enters the protected management handoff when Network Apply is submitted; it does not become an active requested-interface binding at API-save time.

Physical-interface and VLAN role fields accept exactly management, access, route, or unused. The retired services and storage values are rejected on new requests. Appliance startup and settings-archive restore map those values to access only when reading compatible persisted state from an older Atlaso release.

Update physical-interface desired state¶

PATCH /api/v1/interfaces/physical/{name} accepts the typed PhysicalInterfaceUpdate schema. Omit a property to keep its saved value; use an empty string or null only for the documented CIDR and gateway fields that can be cleared. Recognized role, mode, and IPv4-method spellings are case-insensitive. New requests reject the retired services and storage roles; the legacy routed mode spelling remains supported. Atlaso rejects unsupported properties instead of silently ignoring them.

For a static management to access role change, Atlaso captures valid saved IPv4 and IPv6 gateways before clearing those management-only fields. The same PATCH transaction stages or enables the equivalent family default Route on the converted interface. An equivalent saved default is reused; a different existing family default returns 409 and rolls back the interface, routes, dependencies, and audit rows. A missing gateway creates no route. Clients should warn operators that off-subnet routing may be unavailable, then review both Network and Routing & WAN before submitting global Appliance Apply. The PATCH never mutates host routes directly.

Changing a physical interface's IPv4 or IPv6 CIDR automatically refreshes dependent desired-state addresses for DNS, NTP/NTS, Certificate Authority, KMS, LDAP, OIDC, VCF services, ESX Storage, Web Terminal, matching DHCP scopes, and Network Boot/PXE. Atlaso commits the interface and dependent rows as one transaction. If any dependent update fails, none of those changes are saved. Removing an address family or converting an interface to trunk mode is rejected while an enabled service, ESX Storage datastore, DHCP scope, or Network Boot/PXE listener still depends on the address; administratively disabling an interface follows the same rule. Disabling a physical parent also evaluates bindings to its enabled child VLANs. If other selected interfaces remain eligible, Atlaso removes only the ineligible service, Web Terminal, or PXE selection. Disable or move a final binding first. The audit event names the dependent units that were refreshed. This remains a desired-state edit: review the resulting network and service previews, then use global Appliance Apply for host enforcement.

Requested-interface authorization continues to use the last-applied Network management bindings and observed addresses after a successful PATCH. Pending role, address, or access_management_ui_enabled values cannot remove the current management origin or publish a candidate origin early. If the protected Apply fails, is cancelled, or rolls back, the previous binding remains authoritative and the saved desired edit remains available to correct or revert. Web Terminal uses this applied projection for its management page, ticket, and WebSocket eligibility, including flagged access physical interfaces and VLANs. Additional explicitly selected terminal listeners remain on the public plane.

The internal Certificate Authority is the exception: if its last selected portal interface becomes ineligible, Atlaso clears the public CA portal binding and app-owned alias while leaving internal CA custody enabled.

DHCP DNS/NTP scope options accept usable unicast addresses of the correct family on routed networks as well as the local subnet; service addresses need not be Atlaso-owned. Gateway and lease-range subnet rules are unchanged.

DHCP scope gateway, DNS, and NTP values remain operator-owned when they are valid and do not match a replaced interface address. Interface edits update only blank or stale derived values. Enabled reservations that would otherwise leave every enabled scope retain their host offset in the uniquely matching rebased scope; Atlaso updates app-owned reservation DNS records in the same transaction and rejects ambiguous moves. When real scope rows exist, inactive legacy global DHCP binding fields are retained for compatibility but do not constrain interface edits.

Update appliance settings partially¶

PATCH /api/v1/settings is a partial desired-state update. Send only the properties that should change; Atlaso preserves every omitted appliance setting. Explicit false values remain valid for switches, and an empty external_dns_servers list clears that collection. An empty web_terminal_interfaces list clears additional Web Terminal bindings; while Web Terminal is enabled, Atlaso retains its mandatory management listener. null is not a clearing form for this operation and returns 422; omit the property instead.

Changing appliance_fqdn reconciles factory-derived service identities and app-owned DNS records only when the property is present and its normalized value differs from the saved FQDN. Other settings PATCH requests do not trigger that domain reconciliation. These API edits save desired state only, except for the documented immediate authentication lifetime policies. Review resulting changes and use global Appliance Apply for host enforcement.

Scopes and authorization¶

Each Swagger operation describes its required Atlaso scope or authentication posture. A token can call only operations covered by its scopes; prefer a read-only token when the client does not mutate desired state. A valid token with insufficient scope receives 403 Forbidden. Missing, invalid, expired, or revoked credentials receive 401 Unauthorized.

Understand responses¶

Successful responses use the operation's documented response model. Common failure statuses include:

Atlaso errors use the ProblemDetails contract:

API and background fetch clients retain structured authentication and permission errors. Full browser navigation uses the appropriate login recovery surface; this does not change the API error status or response contract.

{
  "type": "https://atlaso.example/problems/validation",
  "title": "Request validation failed",
  "status": 422,
  "detail": "One or more request values are invalid.",
  "instance": "/api/v1/example",
  "error_code": "request_validation_failed",
  "request_id": "req_example123"
}

The X-Request-ID response header and the request_id problem field identify the same request for troubleshooting. Record them without recording credentials or sensitive payload values.

For audited mutations using record_audit, optional App-log publication after the audit commit cannot turn a committed save into a failure response. If retained App-log capture fails, the saved state and Audit event remain durable; investigate the value-free event=audit_post_commit_reporting_failed process diagnostic. This does not relax durable capture requirements for individual App records.

Immediate and applied effects¶

Read each mutation's description before calling it. Some operations change application state immediately, some queue a durable job, and some save desired state only. Desired-state edits do not mutate the host by themselves: /ui/management/appliance-apply remains the reviewed global host-mutation workflow. A successful save means Atlaso accepted the desired state, not that the corresponding service is already applied. Follow returned job identifiers through the Jobs or Tasks interfaces and verify terminal results.

GET /api/v1/routes-wan/settings requires both read:routes and read:wan. PUT on the same path requires both write:routes and write:wan and replaces routing_enabled, nat_enabled, and wan_simulation_enabled. Responses also include read-only effective_nat_enabled, which is true only when Routing and NAT are both enabled. The update is audited and saves desired state only; it preserves every route, routing permission, NAT rule, WAN policy, and assignment until the wan Appliance Apply unit runs.

The generic Services enable and disable operations for routing update the same saved routing_enabled value. Services start, stop, and restart operations reject routing with HTTP 422 because runtime forwarding changes must use the wan Appliance Apply unit.

GET /api/v1/wan/status reports active policy assignments only while WAN Simulation is enabled. Its managed-interface list includes both inbound and outbound interfaces of enabled NAT rules only while both Routing and NAT are enabled, so preserved inactive rows are not reported as active runtime intent. Shared interfaces appear once in the sorted list.

Legacy /api/v1/dns/apply, /api/v1/dhcp/apply, and /api/v1/firewall/apply routes remain available for compatibility but are intentionally absent from Swagger because they predate the reviewed global workflow. New clients must save desired state and use /ui/management/appliance-apply; do not build new automation around the legacy direct-apply routes. The legacy Firewall Apply response retains its validation result. If valid is false, reloaded is false and the configuration is not applied; this includes disabled Firewall states that cannot enforce routing denials. It also rejects pending routing permission fingerprints, including a removed or disabled permission, routing-switch change, or changed target topology. Apply Routing & WAN and Firewall together through global Appliance Apply first. Once both executed baselines match current routing intent, the compatibility route can apply unrelated Firewall changes without advancing either paired baseline.

Delete an ESXi Host Reference¶

DELETE /api/v1/esxi-pxe/hosts/{host_id} requires write:esxi-pxe and removes one saved Host Reference. By default, Atlaso retains matching Network Boot discovery history so the host can be rediscovered or promoted again. The response reports whether the reference was deleted and returns zero removal counts for discovered hosts, reports, sessions, and commands.

Set remove_discovered_host=true only when the client also has write:pxe and the administrator intends to remove matching discovery commands, sessions, reports, and host rows in the same transaction. Atlaso returns 409 Conflict without mutation when another Host Reference owns any reported MAC for that discovery; delete without cleanup or remove the other assignment first. A successful deletion changes saved desired state immediately, while generated PXE state changes only through global Appliance Apply.

Authorize one ESXi boot¶

This operation is used when the applied Boot Service Require console authorization switch is enabled. The switch defaults off; after a successful ESXi PXE Apply, assigned hosts can continue without this API call. Saving the desired switch alone does not change the running policy. Both modes retain per-attempt, single-use capabilities.

POST /api/v1/network-boot/esxi-hosts/{host_id}/authorize-boot-once requires write:pxe and accepts JSON containing the boot_code displayed by the exact pending host-console attempt, for example {"boot_code":"ABCD-EFGH"}. Start Network Boot and choose the assigned ESXi entry before calling this operation. It does not modify desired state and does not replace global Appliance Apply. The response contains only the host ID, issue and expiry timestamps, and secret-free operator guidance; it never contains the capability or a credential-bearing URL.

The authorization lasts ten minutes, is consumed by the first matching Kickstart retrieval, and is bound to the exact applied host, full applied Kickstart revision, applied HTTP listener, and generated boot attempt. A 409 means the code is invalid or expired, the desired Host Reference has drifted, or exact applied state is unavailable; start a new host attempt or review and apply Network Boot state before retrying. Continue the intended host promptly after a 202 response, and never collect PXE URLs from packet traces or boot consoles in tickets, logs, screenshots, or automation output.

Troubleshoot clients¶

• Confirm /openapi.json is reachable and every client URL begins with /api/v1.
• Check token expiry, revocation, and required scopes before replacing credentials.
• For 422, compare parameter formats and allowed values with Swagger and inspect the returned ProblemDetails.
• For 423, identify the active task and retry only after its terminal result.
• For unexpected failures, preserve the status, error_code, and request ID, then inspect Atlaso operational logs.

Atlaso preserves existing operation IDs, request and response shapes, authentication behavior, and versioned paths within the published compatibility contract. Additive fields may appear. Clients should ignore unknown response fields and must not depend on browser pages or non-/api/v1 protocol routes as generated REST-client contracts.

Managed reverse proxies¶

/api/v1/traffic-publishing/reverse-proxies is the Firewall-scoped desired-state collection. GET and POST list and create complete proxies; GET and PUT /{proxy_id} read and replace one complete proxy, including its ordered routes; DELETE /{proxy_id} removes it. GET and PUT /{proxy_id}/routes read or replace the complete route list. Read operations require read:firewall; mutations require write:firewall. Writes save desired state only and the global Appliance Apply workflow owns publication. GET /health returns bounded cached route observations and applied or pending state without probing on the request or returning upstream bodies. Refer to the reverse-proxy operator guide for field behavior, health freshness, and recovery.

NAT ingress compatibility¶

Destination translations use the separate /api/v1/traffic-publishing/port-forwards collection. CRUD and status require read:firewall or write:firewall as appropriate; legacy WAN scopes do not grant access. Complete create and replace requests define one exact listener and equal-length port mapping. Writes save desired state only, and validation failures use ProblemDetails without committing a partial rule. The bounded status operation returns nullable packet/byte counters and pending, applied, suspended, disabled, or degraded state. See the port-forward API contract for methods and source-loss acknowledgement.

POST /api/v1/nat/rules and PATCH /api/v1/nat/rules/{rule_id} accept inbound_interfaces, an array of explicit interface/VLAN names. New rules and enabled updates require at least one enabled same-family lab target different from outbound_interface. Existing paths, operation IDs, and read:wan / write:wan authorization remain unchanged. Clients must supply reviewed ingress membership when creating rules. PATCH preserves saved membership when the field is omitted and validates that membership when enabling or changing the outbound target. Explicit [] clears membership only on a disabled rule; an omitted field never means all interfaces. Responses return the saved array, including an empty array for legacy rows awaiting review. A disabled legacy update may retain an empty scope. The create-specific OpenAPI schema marks inbound_interfaces as required with at least one item, including for disabled new rules; update and response schemas preserve empty legacy scopes. Source Group and CIDR values restrict addresses within the selected ingress. All writes save desired state; global Appliance Apply owns enforcement.

Traffic Publishing adds ip_family (4 or 6), translation_mode (masquerade or snat), and translated_address. Fixed SNAT requires the exact same-family egress address; source CIDRs and Source Groups must match the chosen family. PATCH preserves omitted additive fields. The legacy masquerade response remains a mode projection. Canonical GET/PUT /api/v1/traffic-publishing/settings use Firewall read/write scopes and share one NAT setting with the deprecated Routes/WAN projection. Only Routing owns forwarding, and the separate nat Apply unit owns translation. See Traffic Publishing for settings, upgrade, and runtime recovery details.

Inbound and outbound names always use 1–80 ASCII letters, digits, underscores, dots, colons, or hyphens, including for disabled rows and settings archives. Disabling a rule relaxes target availability checks only; it does not relax name syntax or ingress-list structure.