# LitmusEdge 4.0.x API Documentation/System/Access Control - LE, LEM, LUNS API Docs ## Get User Roles **GET** `{{edgeUrl}}/auth/v3/roles` # Get User Roles Returns every role defined on the device. Built-in roles (`Administrator`, `Viewer`) have `system: true` and cannot be deleted. ## Endpoint ```http GET {{edgeUrl}}/auth/v3/roles ``` ## Authentication HTTP Basic Auth. **Username** is your API token, **password** is empty. Tokens are managed under `System > Access Control > Tokens`. ## Response `200 OK` -- `application/json` | Field | Type | Description | |----------|---------|-------------------------------------------------------------------| | `id` | string | Role ID. Built-in roles use `default_*_role`; custom roles use a UUID. | | `name` | string | Display name. | | `system` | boolean | `true` for built-in roles. | ```json [ { "id": "default_admin_role", "name": "Administrator", "system": true }, { "id": "default_viewer_role", "name": "Viewer", "system": true } ] ``` ## Errors | HTTP status | When it happens | |---------------------|--------------------------------------------------------------------------------| | `400 Bad Request` | Missing or malformed query/body parameter. | | `401 Unauthorized` | Missing or invalid credentials. | | `403 Forbidden` | Token lacks permission for this operation. | | `404 Not Found` | Target entity does not exist. | | `5xx` | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. | > **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly. ### Response **Status**: 200 OK ```json [ { "id": "default_admin_role", "name": "Administrator", "system": true }, { "id": "default_viewer_role", "name": "Viewer", "system": true } ] ``` --- ## Add New Role **POST** `{{edgeUrl}}/auth/v3/roles` # Add New Role Creates a new role with the supplied permission set. Permissions are grouped by service (`access`, `analytics`, `auth`, `dm`, `lic`, `sysinfo`, `css`, `stats`, `dh`, ...) and each is a list of action strings (`View`, `Modify`, `ChangePassword`, `AcceptEula`, `ViewDevices`, ...). ## Endpoint ```http POST {{edgeUrl}}/auth/v3/roles ``` ## Authentication HTTP Basic Auth. **Username** is your API token, **password** is empty. Tokens are managed under `System > Access Control > Tokens`. ## Request body ```json { "role": { "name": "{{new-user-role}}", "permissions": { "access": ["View"], "analytics": ["View", "Modify"], "auth": ["View", "AcceptEula", "ChangePassword"], "dm": ["View"], "lic": ["View"], "sysinfo": ["View"], "css": ["View"], "stats": ["View"], "dh": ["View", "ViewDevices", "ViewDrivers", "ViewTags"] } } } ``` ## Response `200 OK` -- `application/json` ```json { "id": "731afed4-7a94-47f9-ae93-205ad5b047f8" } ``` ## Errors | HTTP status | When it happens | |---------------------|--------------------------------------------------------------------------------| | `400 Bad Request` | Missing or malformed query/body parameter. | | `401 Unauthorized` | Missing or invalid credentials. | | `403 Forbidden` | Token lacks permission for this operation. | | `404 Not Found` | Target entity does not exist. | | `5xx` | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. | > **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly. ### Request Body ```json { "role": { "name": "{{new-user-role}}", "permissions": { "access": [ "View" ], "analytics": [ "View", "Modify" ], "auth": [ "View", "AcceptEula", "ChangePassword" ], "dm": [ "View" ], "lic": [ "View" ], "sysinfo": [ "View" ], "css": [ "View" ], "stats": [ "View" ], "dh": [ "View", "ViewDevices", "ViewDrivers", "ViewTags" ], "dt": [ "View" ], "dl": [ "Modify", "View" ], "events": [ "Modify", "View" ], "ftp": [ "View" ], "flows": [ "Modify", "View" ], "cc": [ "Modify", "View" ], "mp": [ "Modify", "View" ], "nd": [ "Modify", "View" ], "opcua": [ "View" ] } } } ``` ### Response **Status**: 200 OK ```json { "id": "731afed4-7a94-47f9-ae93-205ad5b047f8" } ``` --- ## Update User Role **PUT** `{{edgeUrl}}/auth/v3/roles/{{system-user-role-id}}` # Update User Role Updates an existing role's permissions. Send the **full permission set** -- omitted services are reset to empty. ## Endpoint ```http PUT {{edgeUrl}}/auth/v3/roles/{{system-user-role-id}} ``` ## Authentication HTTP Basic Auth. **Username** is your API token, **password** is empty. Tokens are managed under `System > Access Control > Tokens`. ## Path parameters | Location | Name | Required | Description | |----------|---------------------------------|----------|----------------------------------------------------------| | Path | `{{system-user-role-id}}` | Yes | Role ID from `Get User Roles`. | ## Request body Same shape as `Add New Role`. ## Errors | HTTP status | When it happens | |---------------------|--------------------------------------------------------------------------------| | `400 Bad Request` | Missing or malformed query/body parameter. | | `401 Unauthorized` | Missing or invalid credentials. | | `403 Forbidden` | Token lacks permission for this operation. | | `404 Not Found` | Target entity does not exist. | | `5xx` | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. | > **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly. ### Request Body ```json { "role": { "name": "{{new-user-role}}", "permissions": { "access": [ "View" ], "auth": [ "View", "ChangePassword", "AcceptEula" ], "css": [ "View" ], "dh": [ "View", "ViewDevices", "ViewDrivers", "ViewTags" ], "dm": [ "View", "Modify" ], "lic": [ "View" ], "sysinfo": [ "View" ], "analytics": [ "View" ], "stats": [ "View", "Modify" ], "dt": [ "View" ], "dl": [ "View" ], "events": [ "View", "Modify" ], "ftp": [ "View" ], "flows": [ "View" ], "cc": [ "View" ], "mp": [ "View", "Modify" ], "nd": [ "View", "Modify" ], "opcua": [ "View", "Modify" ] } } } ``` ### Response **Status**: 204 No Content --- ## Delete User Role **DELETE** `{{edgeUrl}}/auth/v3/roles/{{system-user-role-id}}` # Delete User Role Removes a role. Built-in roles (`system: true`) cannot be deleted. ## Endpoint ```http DELETE {{edgeUrl}}/auth/v3/roles/{{system-user-role-id}} ``` ## Authentication HTTP Basic Auth. **Username** is your API token, **password** is empty. Tokens are managed under `System > Access Control > Tokens`. ## Errors | HTTP status | When it happens | |---------------------|--------------------------------------------------------------------------------| | `400 Bad Request` | Missing or malformed query/body parameter. | | `401 Unauthorized` | Missing or invalid credentials. | | `403 Forbidden` | Token lacks permission for this operation. | | `404 Not Found` | Target entity does not exist. | | `5xx` | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. | > **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly. ### Response **Status**: 204 No Content --- ## Get User Groups **GET** `{{edgeUrl}}/auth/v3/groups` # Get User Groups Returns every user group on the device. Built-in groups (`Administrators`, `Viewers`) have `isSystem: true`. ## Endpoint ```http GET {{edgeUrl}}/auth/v3/groups ``` ## Authentication HTTP Basic Auth. **Username** is your API token, **password** is empty. Tokens are managed under `System > Access Control > Tokens`. ## Response ```json [ { "groupId": "default_admins_group", "groupName": "Administrators", "isSystem": true }, { "groupId": "default_viewers_group", "groupName": "Viewers", "isSystem": true } ] ``` ## Errors | HTTP status | When it happens | |---------------------|--------------------------------------------------------------------------------| | `400 Bad Request` | Missing or malformed query/body parameter. | | `401 Unauthorized` | Missing or invalid credentials. | | `403 Forbidden` | Token lacks permission for this operation. | | `404 Not Found` | Target entity does not exist. | | `5xx` | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. | > **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly. ### Response **Status**: 200 OK ```json [ { "groupId": "cff71351-c16e-4a61-a07a-72f9365ce411", "groupName": "custom-group", "isSystem": false }, { "groupId": "default_admins_group", "groupName": "Administrators", "isSystem": true }, { "groupId": "default_viewers_group", "groupName": "Viewers", "isSystem": true } ] ``` --- ## Create User Group **POST** `{{edgeUrl}}/auth/v3/groups` # Create User Group Creates a new group. Use `Add Users to Group` to populate it. ## Endpoint ```http POST {{edgeUrl}}/auth/v3/groups ``` ## Authentication HTTP Basic Auth. **Username** is your API token, **password** is empty. Tokens are managed under `System > Access Control > Tokens`. ## Request body ```json { "group": { "groupName": "custom-group" } } ``` ## Response ```json { "groupId": "814b108c-dbb0-4640-9018-6577c4540e16" } ``` ## Errors | HTTP status | When it happens | |---------------------|--------------------------------------------------------------------------------| | `400 Bad Request` | Missing or malformed query/body parameter. | | `401 Unauthorized` | Missing or invalid credentials. | | `403 Forbidden` | Token lacks permission for this operation. | | `404 Not Found` | Target entity does not exist. | | `5xx` | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. | > **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly. ### Request Body ```json { "group": { "groupName": "custom-group" } } ``` ### Response **Status**: 200 OK ```json { "groupId": "814b108c-dbb0-4640-9018-6577c4540e16" } ``` --- ## Get User Group Details **GET** `{{edgeUrl}}/auth/v3/groups/{{user-group}}` # Get User Group Details Returns one group plus its `roles[]` and `users[]` membership. ## Endpoint ```http GET {{edgeUrl}}/auth/v3/groups/{{user-group}} ``` ## Authentication HTTP Basic Auth. **Username** is your API token, **password** is empty. Tokens are managed under `System > Access Control > Tokens`. ## Response `roles` and `users` are `null` (not `[]`) while the group is empty. Once populated, each entry carries both its ID and its display name: ```json { "groupId": "default_viewers_group", "groupName": "Viewers", "isSystem": true, "isAdmin": false, "roles": [ { "roleId": "default_viewer_role", "roleName": "Viewer" } ], "users": null } ``` Use `Assign Roles to Group` to change `roles[]` and `Add Users to Group` to change membership. ## Errors | HTTP status | When it happens | |---------------------|--------------------------------------------------------------------------------| | `400 Bad Request` | Missing or malformed query/body parameter. | | `401 Unauthorized` | Missing or invalid credentials. | | `403 Forbidden` | Token lacks permission for this operation. | | `404 Not Found` | Target entity does not exist. | | `5xx` | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. | > **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly. ### Response **Status**: 200 OK ```json { "groupId": "default_viewers_group", "groupName": "Viewers", "isSystem": true, "isAdmin": false, "roles": [ { "roleId": "default_viewer_role", "roleName": "Viewer" } ], "users": null } ``` --- ## Add Users to Group **PUT** `{{edgeUrl}}/auth/v3/users/{{user-id}}/groups` # Add Users to Group Assigns one user to one or more groups. The path identifies the user; the body lists the groups to add. ## Endpoint ```http PUT {{edgeUrl}}/auth/v3/users/{{user-id}}/groups ``` ## Authentication HTTP Basic Auth. **Username** is your API token, **password** is empty. Tokens are managed under `System > Access Control > Tokens`. ## Path parameters | Location | Name | Required | Description | |----------|----------------|----------|----------------------------------------------| | Path | `{{user-id}}` | Yes | User ID. | ## Request body ```json { "groups": ["{{user-group}}"] } ``` ## Errors | HTTP status | When it happens | |---------------------|--------------------------------------------------------------------------------| | `400 Bad Request` | Missing or malformed query/body parameter. | | `401 Unauthorized` | Missing or invalid credentials. | | `403 Forbidden` | Token lacks permission for this operation. | | `404 Not Found` | Target entity does not exist. | | `5xx` | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. | > **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly. ### Request Body ```json { "groups": [ "{{user-group}}" ] } ``` ### Response **Status**: 204 No Content --- ## Assign Roles to Group **PUT** `{{edgeUrl}}/auth/v3/groups/{{user-group}}/roles` # Assign Roles to Group Replaces the set of roles attached to a group. The path identifies the group; the body lists the role IDs it should hold. This is a **replace**, not a merge: the `roles` array you send becomes the group's complete role set. Send the full list every time, and send an empty array to strip every role from the group. Members of the group inherit the permissions of every role listed here. Use `Get User Roles` to look up the role IDs, and `Get User Group Details` to read back the result. ## Endpoint ```http PUT {{edgeUrl}}/auth/v3/groups/{{user-group}}/roles ``` ## Authentication HTTP Basic Auth. **Username** is your API token, **password** is empty. Tokens are managed under `System > Access Control > Tokens`. ## Path parameters | Location | Name | Required | Description | |----------|------------------|----------|------------------------------------------------| | Path | `{{user-group}}` | Yes | Group ID from `Get User Groups`. | ## Request body ```json { "roles": ["default_viewer_role"] } ``` | Field | Type | Required | Description | |---------|------------|----------|---------------------------------------------------------| | `roles` | string[] | Yes | Role IDs from `Get User Roles`. Replaces the whole set. | ## Response `204 No Content` on success. The endpoint returns no body. > This endpoint resolves the caller's own user account before it applies the change. A bare API-credential token that is not bound to a user is rejected with `401` and `{"error":{"Msg":"token doesn't contain a valid user id"}}`. Call it with a user-bound session token. ## Errors | HTTP status | When it happens | |---------------------|--------------------------------------------------------------------------------| | `400 Bad Request` | Missing or malformed query/body parameter. | | `401 Unauthorized` | Missing or invalid credentials. | | `403 Forbidden` | Token lacks permission for this operation. | | `404 Not Found` | Target entity does not exist. | | `5xx` | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. | > **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly. ### Request Body ```json { "roles": [ "{{system-user-role-id}}" ] } ``` ### Response **Status**: 204 No Content --- ## Update Group Name **PUT** `{{edgeUrl}}/auth/v3/groups/{{user-group}}` # Update Group Name Renames an existing group. The group ID is preserved. ## Endpoint ```http PUT {{edgeUrl}}/auth/v3/groups/{{user-group}} ``` ## Authentication HTTP Basic Auth. **Username** is your API token, **password** is empty. Tokens are managed under `System > Access Control > Tokens`. ## Request body ```json { "group": { "groupName": "custom-group-1" } } ``` ## Errors | HTTP status | When it happens | |---------------------|--------------------------------------------------------------------------------| | `400 Bad Request` | Missing or malformed query/body parameter. | | `401 Unauthorized` | Missing or invalid credentials. | | `403 Forbidden` | Token lacks permission for this operation. | | `404 Not Found` | Target entity does not exist. | | `5xx` | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. | > **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly. ### Request Body ```json { "group": { "groupName": "custom-group-1" } } ``` ### Response **Status**: 204 No Content --- ## List Users **GET** `{{edgeUrl}}/auth/v3/users` # List Users Returns every local user on the device. Excludes users from federated auth providers (LDAP / OIDC). ## Endpoint ```http GET {{edgeUrl}}/auth/v3/users ``` ## Authentication HTTP Basic Auth. **Username** is your API token, **password** is empty. Tokens are managed under `System > Access Control > Tokens`. ## Response | Field | Type | Description | |--------------------------|---------|-------------------------------------------------------------------| | `userId` | string | Immutable user UUID. Use this as the `{{user-id}}` path parameter. | | `username` | string | Login name. | | `firstName` / `lastName` | string | Display name. | | `disabled` | boolean | `true` when the account is disabled. | | `isAdmin` | boolean | `true` when the user holds administrator privileges. | | `mustChangePassword` | boolean | `true` if the user must change password on next login. | | `mfaEnabled` | boolean | `true` when multi-factor authentication is enabled for the user. | | `external` | boolean | `true` for users backed by a federated provider (LDAP / OIDC). | | `eulaAcceptedTs` | string | RFC 3339 timestamp of EULA acceptance; absent if not accepted. | | `createdAt` | string | RFC 3339 timestamp of account creation. | | `modifiedAt` | string | RFC 3339 timestamp of the last modification. | > `eulaAcceptedTs`, `createdAt` and `modifiedAt` are RFC 3339 **strings** (for example `"2025-07-14T12:21:22-07:00"`), not numeric timestamps. The offset is the device's local timezone, so do not assume a `Z` suffix. ## Response example ```json [ { "userId": "f5ed6b65-746f-4933-9bc6-0c617818f09b", "username": "admin", "firstName": "System", "lastName": "Administrator", "mustChangePassword": false, "mfaEnabled": false, "disabled": false, "isAdmin": true, "eulaAcceptedTs": "2025-07-14T12:21:22-07:00", "external": false, "createdAt": "2026-02-19T11:41:39-08:00", "modifiedAt": "2026-02-19T11:41:39-08:00" } ] ``` ## Errors | HTTP status | When it happens | |---------------------|--------------------------------------------------------------------------------| | `400 Bad Request` | Missing or malformed query/body parameter. | | `401 Unauthorized` | Missing or invalid credentials. | | `403 Forbidden` | Token lacks permission for this operation. | | `404 Not Found` | Target entity does not exist. | | `5xx` | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. | > **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly. ### Response **Status**: 200 OK ```json [ { "userId": "f5ed6b65-746f-4933-9bc6-0c617818f09b", "username": "admin", "firstName": "System", "lastName": "Administrator", "mustChangePassword": false, "mfaEnabled": false, "disabled": false, "isAdmin": true, "eulaAcceptedTs": "2025-07-14T12:21:22-07:00", "external": false, "createdAt": "2026-02-19T11:41:39-08:00", "modifiedAt": "2026-02-19T11:41:39-08:00" }, { "userId": "8c0752a5-c343-4fac-b9e8-aa0b5e876826", "username": "jcarter3", "firstName": "John", "lastName": "Carter", "mustChangePassword": false, "mfaEnabled": false, "disabled": false, "isAdmin": false, "eulaAcceptedTs": "2026-08-13T13:52:43Z", "external": false, "createdAt": "2026-08-01T09:14:02-07:00", "modifiedAt": "2026-08-13T13:52:43Z" } ] ``` --- ## Create an User **POST** `{{edgeUrl}}/auth/v3/users` # Create an User Creates a new local user. The password is set at create time; `mustChangePassword: true` forces the user to choose a new one at first login. ## Endpoint ```http POST {{edgeUrl}}/auth/v3/users ``` ## Authentication HTTP Basic Auth. **Username** is your API token, **password** is empty. Tokens are managed under `System > Access Control > Tokens`. ## Request body ```json { "user": { "firstName": "John", "lastName": "Carter", "username": "jcarter3", "mustChangePassword": true, "password": "Litmus@1", "passwordConfirmation": "Litmus@1" } } ``` | Field | Type | Required | Description | |------------------------|---------|----------|----------------------------------------------------------| | `username` | string | Yes | Login name. Unique across local users. | | `firstName` / `lastName` | string | Yes | Display name. | | `password` | string | Yes | Initial password. | | `passwordConfirmation` | string | Yes | Must match `password` exactly. | | `mustChangePassword` | boolean | No | Force password change at first login. | ## Errors | HTTP status | When it happens | |---------------------|--------------------------------------------------------------------------------| | `400 Bad Request` | Missing or malformed query/body parameter. | | `401 Unauthorized` | Missing or invalid credentials. | | `403 Forbidden` | Token lacks permission for this operation. | | `404 Not Found` | Target entity does not exist. | | `5xx` | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. | > **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly. ### Request Body ```json { "user": { "firstName": "John", "lastName": "Carter", "username": "jcarter3", "mustChangePassword": true, "password": "Litmus@1", "passwordConfirmation": "Litmus@1" } } ``` ### Response **Status**: 200 OK ```json { "disabled": false, "firstName": "John", "lastName": "Carter", "mustChangePassword": true, "username": "jcarter3" } ``` --- ## Update an User **PUT** `{{edgeUrl}}/auth/v2/users/{{user-name}}` # Update an User Updates a user record. Note this endpoint targets the **v2** path (`/auth/v2/users/...`) rather than the v3 surface used elsewhere in this folder. ## Endpoint ```http PUT {{edgeUrl}}/auth/v2/users/{{user-name}} ``` ## Authentication HTTP Basic Auth. **Username** is your API token, **password** is empty. Tokens are managed under `System > Access Control > Tokens`. ## Path parameters | Location | Name | Required | Description | |----------|------------------|----------|----------------------------------------------| | Path | `{{user-name}}` | Yes | User name. | ## Request body ```json { "disabled": false, "firstName": "John", "lastName": "Carter", "mustChangePassword": true, "password": "******", "username": "jc123" } ``` ## Errors | HTTP status | When it happens | |---------------------|--------------------------------------------------------------------------------| | `400 Bad Request` | Missing or malformed query/body parameter. | | `401 Unauthorized` | Missing or invalid credentials. | | `403 Forbidden` | Token lacks permission for this operation. | | `404 Not Found` | Target entity does not exist. | | `5xx` | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. | > **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly. ### Request Body ```json { "disabled": false, "eulaAcceptedTs": 5478670544326924000, "firstName": "John", "lastName": "Carter", "mustChangePassword": true, "password": "******", "username": "jc123" } ``` ### Response **Status**: 204 No Content --- ## Remove an User **DELETE** `{{edgeUrl}}/auth/v2/users/{{user-name}}` # Remove an User Removes a local user. Active sessions for that user are terminated on the next round-trip. ## Endpoint ```http DELETE {{edgeUrl}}/auth/v2/users/{{user-name}} ``` ## Authentication HTTP Basic Auth. **Username** is your API token, **password** is empty. Tokens are managed under `System > Access Control > Tokens`. ## Errors | HTTP status | When it happens | |---------------------|--------------------------------------------------------------------------------| | `400 Bad Request` | Missing or malformed query/body parameter. | | `401 Unauthorized` | Missing or invalid credentials. | | `403 Forbidden` | Token lacks permission for this operation. | | `404 Not Found` | Target entity does not exist. | | `5xx` | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. | > **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly. ### Response **Status**: 204 No Content --- ## Active Online Users **GET** `{{edgeUrl}}/auth/v3/users/active` # Active Online Users Returns the users currently authenticated to the LE UI. Same payload as `Dashboard > Active Online Users`. ## Endpoint ```http GET {{edgeUrl}}/auth/v3/users/active ``` ## Authentication HTTP Basic Auth. **Username** is your API token, **password** is empty. Tokens are managed under `System > Access Control > Tokens`. ## Response ```json [ { "userId": "admin", "username": "admin", "firstName": "System", "lastName": "Administrator" } ] ``` ## Errors | HTTP status | When it happens | |---------------------|--------------------------------------------------------------------------------| | `400 Bad Request` | Missing or malformed query/body parameter. | | `401 Unauthorized` | Missing or invalid credentials. | | `403 Forbidden` | Token lacks permission for this operation. | | `404 Not Found` | Target entity does not exist. | | `5xx` | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. | > **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly. ### Response **Status**: 200 OK ```json [ { "userId": "admin", "username": "admin", "firstName": "System", "lastName": "Administrator" } ] ``` --- ## Enable NATS Proxy **PUT** `{{edgeUrl}}/access/proxy/enable` # Enable NATS Proxy Enables the on-device NATS proxy, which lets external clients reach the device's internal NATS message bus. Access accounts (see `Tokens > Access Accounts`) restrict what topics each client can read or write. ## Endpoint ```http PUT {{edgeUrl}}/access/proxy/enable ``` ## Authentication HTTP Basic Auth. **Username** is your API token, **password** is empty. Tokens are managed under `System > Access Control > Tokens`. ## Errors | HTTP status | When it happens | |---------------------|--------------------------------------------------------------------------------| | `400 Bad Request` | Missing or malformed query/body parameter. | | `401 Unauthorized` | Missing or invalid credentials. | | `403 Forbidden` | Token lacks permission for this operation. | | `404 Not Found` | Target entity does not exist. | | `5xx` | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. | > **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly. ### Response **Status**: 204 No Content --- ## Disable NATS Proxy **PUT** `{{edgeUrl}}/access/proxy/disable` # Disable NATS Proxy Disables the on-device NATS proxy. External NATS clients are disconnected. ## Endpoint ```http PUT {{edgeUrl}}/access/proxy/disable ``` ## Authentication HTTP Basic Auth. **Username** is your API token, **password** is empty. Tokens are managed under `System > Access Control > Tokens`. ## Errors | HTTP status | When it happens | |---------------------|--------------------------------------------------------------------------------| | `400 Bad Request` | Missing or malformed query/body parameter. | | `401 Unauthorized` | Missing or invalid credentials. | | `403 Forbidden` | Token lacks permission for this operation. | | `404 Not Found` | Target entity does not exist. | | `5xx` | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. | > **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly. ### Response **Status**: 204 No Content --- ## Get API Keys **GET** `{{edgeUrl}}/auth/v2/apikeys` # Get API Keys Returns every API key on the device. The `value` field is the secret the key holder uses to authenticate -- treat this response as sensitive. ## Endpoint ```http GET {{edgeUrl}}/auth/v2/apikeys ``` ## Authentication HTTP Basic Auth. **Username** is your API token, **password** is empty. Tokens are managed under `System > Access Control > Tokens`. ## Response ```json [ { "id": "a1b2c3d4-a1b2-c3d4-a1b2-a1b2c3d4a1b2", "name": "testKey", "readOnly": false, "value": "abcdabcdabcdabcdabcdabcdabcdabcd" } ] ``` ## Errors | HTTP status | When it happens | |---------------------|--------------------------------------------------------------------------------| | `400 Bad Request` | Missing or malformed query/body parameter. | | `401 Unauthorized` | Missing or invalid credentials. | | `403 Forbidden` | Token lacks permission for this operation. | | `404 Not Found` | Target entity does not exist. | | `5xx` | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. | > **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly. ### Response **Status**: 200 OK ```json [ { "id": "a1b2c3d4-a1b2-c3d4-a1b2-a1b2c3d4a1b2", "name": "testKey", "readOnly": false, "value": "abcdabcdabcdabcdabcdabcdabcdabcd" }, { "id": "system_api_key", "name": "System API key (read only)", "readOnly": true, "value": "abcdabcdabcdabcdabcdabcdabcdabcd" } ] ``` --- ## Create API Key **POST** `{{edgeUrl}}/auth/v2/apikeys` # Create API Key Creates a new API key with the given name. The key value is generated server-side and returned in the response. **Save it immediately** -- it cannot be retrieved later. ## Endpoint ```http POST {{edgeUrl}}/auth/v2/apikeys ``` ## Authentication HTTP Basic Auth. **Username** is your API token, **password** is empty. Tokens are managed under `System > Access Control > Tokens`. ## Request body ```json { "name": "testAPIKey" } ``` ## Errors | HTTP status | When it happens | |---------------------|--------------------------------------------------------------------------------| | `400 Bad Request` | Missing or malformed query/body parameter. | | `401 Unauthorized` | Missing or invalid credentials. | | `403 Forbidden` | Token lacks permission for this operation. | | `404 Not Found` | Target entity does not exist. | | `5xx` | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. | > **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly. ### Request Body ```json { "name": "testAPIKey" } ``` ### Response **Status**: 204 No Content --- ## Validate API Key **POST** `{{edgeUrl}}/auth/v2/apikeys/validate` # Validate API Key Tests whether a key value is valid. Useful from a custom UI to preview a key before storing it. ## Endpoint ```http POST {{edgeUrl}}/auth/v2/apikeys/validate ``` ## Authentication HTTP Basic Auth. **Username** is your API token, **password** is empty. Tokens are managed under `System > Access Control > Tokens`. ## Request body ```json { "value": "testAPIKey" } ``` ## Errors | HTTP status | When it happens | |---------------------|--------------------------------------------------------------------------------| | `400 Bad Request` | Missing or malformed query/body parameter. | | `401 Unauthorized` | Missing or invalid credentials. | | `403 Forbidden` | Token lacks permission for this operation. | | `404 Not Found` | Target entity does not exist. | | `5xx` | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. | > **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly. ### Request Body ```json { "value":"testAPIKey" } ``` ### Response **Status**: 204 No Content --- ## Show API Key by ID **GET** `{{edgeUrl}}/auth/v2/apikeys/{{api_key_id}}` # Show API Key by ID Returns a single API key by its UUID. Same shape as one element of `Get API Keys`. The secret `value` is returned -- treat as sensitive. ## Endpoint ```http GET {{edgeUrl}}/auth/v2/apikeys/{{api_key_id}} ``` ## Authentication HTTP Basic Auth. **Username** is your API token, **password** is empty. Tokens are managed under `System > Access Control > Tokens`. ## Errors | HTTP status | When it happens | |---------------------|--------------------------------------------------------------------------------| | `400 Bad Request` | Missing or malformed query/body parameter. | | `401 Unauthorized` | Missing or invalid credentials. | | `403 Forbidden` | Token lacks permission for this operation. | | `404 Not Found` | Target entity does not exist. | | `5xx` | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. | > **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly. ### Response **Status**: 200 OK ```json { "id": "a1b2c3d4-a1b2-c3d4-a1b2-a1b2c3d4a1b2", "name": "testKey", "readOnly": false, "value": "abcdabcdabcdabcdabcdabcdabcdabcd" } ``` --- ## Update API Key **PUT** `{{edgeUrl}}/auth/v2/apikeys/{{api_key_id}}` # Update API Key Renames an existing API key. The key value is **not** rotated by this endpoint. ## Endpoint ```http PUT {{edgeUrl}}/auth/v2/apikeys/{{api_key_id}} ``` ## Authentication HTTP Basic Auth. **Username** is your API token, **password** is empty. Tokens are managed under `System > Access Control > Tokens`. ## Request body ```json { "name": "renameTestAPIKey" } ``` ## Errors | HTTP status | When it happens | |---------------------|--------------------------------------------------------------------------------| | `400 Bad Request` | Missing or malformed query/body parameter. | | `401 Unauthorized` | Missing or invalid credentials. | | `403 Forbidden` | Token lacks permission for this operation. | | `404 Not Found` | Target entity does not exist. | | `5xx` | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. | > **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly. ### Request Body ```json { "name": "renameTestAPIKey" } ``` ### Response **Status**: 204 No Content --- ## Delete API Key **DELETE** `{{edgeUrl}}/auth/v2/apikeys/{{api_key_id}}` # Delete API Key Deletes an API key. Subsequent API calls using that key fail with `401 Unauthorized`. ## Endpoint ```http DELETE {{edgeUrl}}/auth/v2/apikeys/{{api_key_id}} ``` ## Authentication HTTP Basic Auth. **Username** is your API token, **password** is empty. Tokens are managed under `System > Access Control > Tokens`. ## Errors | HTTP status | When it happens | |---------------------|--------------------------------------------------------------------------------| | `400 Bad Request` | Missing or malformed query/body parameter. | | `401 Unauthorized` | Missing or invalid credentials. | | `403 Forbidden` | Token lacks permission for this operation. | | `404 Not Found` | Target entity does not exist. | | `5xx` | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. | > **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly. ### Response **Status**: 204 No Content --- ## Create Access Account **POST** `{{edgeUrl}}/access/accounts` # Create Access Account Creates a NATS access account with a server-generated API key. Use `Add Read Topic` / `Add Write Topic` afterwards to grant topic-level access. ## Endpoint ```http POST {{edgeUrl}}/access/accounts ``` ## Authentication HTTP Basic Auth. **Username** is your API token, **password** is empty. Tokens are managed under `System > Access Control > Tokens`. ## Request body ```json { "name": "api_access_account", "enabled": true } ``` ## Response ```json { "id": "31391416-4162-4df5-855e-9b2e0e09536b", "name": "api_access_account", "enabled": true, "apikey": "2936b9f4-2928-494c-8eb4-cdc8bd93b770" } ``` | Field | Type | Description | |------------|---------|----------------------------------------------------------------------------| | `id` | string | Account UUID. Use as `{{access_account_id}}`. | | `apikey` | string | API key the account uses to authenticate to NATS. Use as `{{access_account_api_key}}`. | ## Errors | HTTP status | When it happens | |---------------------|--------------------------------------------------------------------------------| | `400 Bad Request` | Missing or malformed query/body parameter. | | `401 Unauthorized` | Missing or invalid credentials. | | `403 Forbidden` | Token lacks permission for this operation. | | `404 Not Found` | Target entity does not exist. | | `5xx` | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. | > **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly. ### Request Body ```json { "name": "api_access_account", "enabled": true } ``` ### Response **Status**: 200 OK ```json { "id": "31391416-4162-4df5-855e-9b2e0e09536b", "name": "api_access_account", "enabled": true, "apikey": "2936b9f4-2928-494c-8eb4-cdc8bd93b770" } ``` --- ## Get Access Accounts **GET** `{{edgeUrl}}/access/accounts` # Get Access Accounts Returns every access account. The `apikey` is omitted; use `Get Access Account API Key` to retrieve it for a specific account. ## Endpoint ```http GET {{edgeUrl}}/access/accounts ``` ## Authentication HTTP Basic Auth. **Username** is your API token, **password** is empty. Tokens are managed under `System > Access Control > Tokens`. ## Errors | HTTP status | When it happens | |---------------------|--------------------------------------------------------------------------------| | `400 Bad Request` | Missing or malformed query/body parameter. | | `401 Unauthorized` | Missing or invalid credentials. | | `403 Forbidden` | Token lacks permission for this operation. | | `404 Not Found` | Target entity does not exist. | | `5xx` | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. | > **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly. ### Response **Status**: 200 OK ```json [ { "id": "fcf5e5e4-0951-44c1-987a-a021495115b4", "name": "accessAccount", "enabled": true } ] ``` --- ## Get Access Account API Key **GET** `{{edgeUrl}}/access/accounts/{{access_account_id}}` # Get Access Account API Key Returns one access account, including its current `apikey`. Treat the response as sensitive. ## Endpoint ```http GET {{edgeUrl}}/access/accounts/{{access_account_id}} ``` ## Authentication HTTP Basic Auth. **Username** is your API token, **password** is empty. Tokens are managed under `System > Access Control > Tokens`. ## Errors | HTTP status | When it happens | |---------------------|--------------------------------------------------------------------------------| | `400 Bad Request` | Missing or malformed query/body parameter. | | `401 Unauthorized` | Missing or invalid credentials. | | `403 Forbidden` | Token lacks permission for this operation. | | `404 Not Found` | Target entity does not exist. | | `5xx` | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. | > **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly. ### Response **Status**: 200 OK ```json { "id": "fcf5e5e4-0951-44c1-987a-a021495115b4", "name": "accessAccount", "enabled": true, "apikey": "a5775c6d-762f-4d05-9118-b9ed8110fcc8" } ``` --- ## Enable Access Account **PUT** `{{edgeUrl}}/access/accounts/{{access_account_id}}/enable` # Enable Access Account Enables a previously-disabled access account. ## Endpoint ```http PUT {{edgeUrl}}/access/accounts/{{access_account_id}}/enable ``` ## Authentication HTTP Basic Auth. **Username** is your API token, **password** is empty. Tokens are managed under `System > Access Control > Tokens`. ## Errors | HTTP status | When it happens | |---------------------|--------------------------------------------------------------------------------| | `400 Bad Request` | Missing or malformed query/body parameter. | | `401 Unauthorized` | Missing or invalid credentials. | | `403 Forbidden` | Token lacks permission for this operation. | | `404 Not Found` | Target entity does not exist. | | `5xx` | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. | > **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly. ### Response **Status**: 204 No Content --- ## Disable Access Account **PUT** `{{edgeUrl}}/access/accounts/{{access_account_id}}/disable` # Disable Access Account Disables an access account without deleting it. Clients using its API key are disconnected. ## Endpoint ```http PUT {{edgeUrl}}/access/accounts/{{access_account_id}}/disable ``` ## Authentication HTTP Basic Auth. **Username** is your API token, **password** is empty. Tokens are managed under `System > Access Control > Tokens`. ## Errors | HTTP status | When it happens | |---------------------|--------------------------------------------------------------------------------| | `400 Bad Request` | Missing or malformed query/body parameter. | | `401 Unauthorized` | Missing or invalid credentials. | | `403 Forbidden` | Token lacks permission for this operation. | | `404 Not Found` | Target entity does not exist. | | `5xx` | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. | > **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly. ### Response **Status**: 204 No Content --- ## Reset Access Account **PUT** `{{edgeUrl}}/access/accounts/{{access_account_id}}/reset` # Reset Access Account Rotates the account's `apikey`. The new key is returned in the response; the old key stops working immediately. ## Endpoint ```http PUT {{edgeUrl}}/access/accounts/{{access_account_id}}/reset ``` ## Authentication HTTP Basic Auth. **Username** is your API token, **password** is empty. Tokens are managed under `System > Access Control > Tokens`. ## Response ```json { "id": "fcf5e5e4-0951-44c1-987a-a021495115b4", "name": "accessAccount", "enabled": true, "apikey": "3fae4dcf-9852-4a15-adc8-a07f703af9f6" } ``` ## Errors | HTTP status | When it happens | |---------------------|--------------------------------------------------------------------------------| | `400 Bad Request` | Missing or malformed query/body parameter. | | `401 Unauthorized` | Missing or invalid credentials. | | `403 Forbidden` | Token lacks permission for this operation. | | `404 Not Found` | Target entity does not exist. | | `5xx` | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. | > **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly. ### Response **Status**: 200 OK ```json { "id": "fcf5e5e4-0951-44c1-987a-a021495115b4", "name": "accessAccount", "enabled": true, "apikey": "3fae4dcf-9852-4a15-adc8-a07f703af9f6" } ``` --- ## Delete Access Account **DELETE** `{{edgeUrl}}/access/accounts/{{access_account_id}}` # Delete Access Account Permanently deletes an access account. All topic grants are also removed. ## Endpoint ```http DELETE {{edgeUrl}}/access/accounts/{{access_account_id}} ``` ## Authentication HTTP Basic Auth. **Username** is your API token, **password** is empty. Tokens are managed under `System > Access Control > Tokens`. ## Errors | HTTP status | When it happens | |---------------------|--------------------------------------------------------------------------------| | `400 Bad Request` | Missing or malformed query/body parameter. | | `401 Unauthorized` | Missing or invalid credentials. | | `403 Forbidden` | Token lacks permission for this operation. | | `404 Not Found` | Target entity does not exist. | | `5xx` | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. | > **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly. ### Response **Status**: 204 No Content --- ## Account Current Access **GET** `{{edgeUrl}}/access/accounts/access/{{access_account_api_key}}` # Account Current Access Returns the topic-level access grants associated with an API key (rather than an account UUID). The response lists `read[]` and `write[]` topic patterns -- `">"` is the NATS wildcard meaning "any topic". ## Endpoint ```http GET {{edgeUrl}}/access/accounts/access/{{access_account_api_key}} ``` ## Authentication HTTP Basic Auth. **Username** is your API token, **password** is empty. Tokens are managed under `System > Access Control > Tokens`. ## Response ```json { "read": [">"], "write": null } ``` ## Errors | HTTP status | When it happens | |---------------------|--------------------------------------------------------------------------------| | `400 Bad Request` | Missing or malformed query/body parameter. | | `401 Unauthorized` | Missing or invalid credentials. | | `403 Forbidden` | Token lacks permission for this operation. | | `404 Not Found` | Target entity does not exist. | | `5xx` | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. | > **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly. ### Response **Status**: 200 OK ```json { "read": [ ">" ], "write": null } ``` --- ## Add Read Topic **PUT** `{{edgeUrl}}/access/accounts/access/{{access_account_api_key}}?accessType=read&topics={{access_read_topic}}` # Add Read Topic Grants the account read access to one NATS topic pattern. ## Endpoint ```http PUT {{edgeUrl}}/access/accounts/access/{{access_account_api_key}}?accessType=read&topics={{access_read_topic}} ``` ## Authentication HTTP Basic Auth. **Username** is your API token, **password** is empty. Tokens are managed under `System > Access Control > Tokens`. ## Query parameters | Parameter | Type | Required | Description | |----------------|--------|----------|----------------------------------------------------------------------------| | `accessType` | string | Yes | Must be `read`. | | `topics` | string | Yes | NATS topic pattern (`devicehub.alias.>`, `analytics.publish.>`, etc.). | ## Errors | HTTP status | When it happens | |---------------------|--------------------------------------------------------------------------------| | `400 Bad Request` | Missing or malformed query/body parameter. | | `401 Unauthorized` | Missing or invalid credentials. | | `403 Forbidden` | Token lacks permission for this operation. | | `404 Not Found` | Target entity does not exist. | | `5xx` | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. | > **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly. ### Response **Status**: 204 No Content --- ## Remove Read Topic **DELETE** `{{edgeUrl}}/access/accounts/access/{{access_account_api_key}}?accessType=read&topics={{access_read_topic}}` # Remove Read Topic Revokes a previously-granted read topic from the account. ## Endpoint ```http DELETE {{edgeUrl}}/access/accounts/access/{{access_account_api_key}}?accessType=read&topics={{access_read_topic}} ``` ## Authentication HTTP Basic Auth. **Username** is your API token, **password** is empty. Tokens are managed under `System > Access Control > Tokens`. ## Errors | HTTP status | When it happens | |---------------------|--------------------------------------------------------------------------------| | `400 Bad Request` | Missing or malformed query/body parameter. | | `401 Unauthorized` | Missing or invalid credentials. | | `403 Forbidden` | Token lacks permission for this operation. | | `404 Not Found` | Target entity does not exist. | | `5xx` | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. | > **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly. ### Response **Status**: 204 No Content --- ## Add Write Topic **PUT** `{{edgeUrl}}/access/accounts/access/{{access_account_api_key}}?accessType=write&topics={{access_write_topic}}` # Add Write Topic Grants the account write access to one NATS topic pattern. ## Endpoint ```http PUT {{edgeUrl}}/access/accounts/access/{{access_account_api_key}}?accessType=write&topics={{access_write_topic}} ``` ## Authentication HTTP Basic Auth. **Username** is your API token, **password** is empty. Tokens are managed under `System > Access Control > Tokens`. ## Errors | HTTP status | When it happens | |---------------------|--------------------------------------------------------------------------------| | `400 Bad Request` | Missing or malformed query/body parameter. | | `401 Unauthorized` | Missing or invalid credentials. | | `403 Forbidden` | Token lacks permission for this operation. | | `404 Not Found` | Target entity does not exist. | | `5xx` | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. | > **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly. ### Response **Status**: 204 No Content --- ## Remove Write Topic **DELETE** `{{edgeUrl}}/access/accounts/access/{{access_account_api_key}}?accessType=write&topics={{access_write_topic}}` # Remove Write Topic Revokes a previously-granted write topic from the account. ## Endpoint ```http DELETE {{edgeUrl}}/access/accounts/access/{{access_account_api_key}}?accessType=write&topics={{access_write_topic}} ``` ## Authentication HTTP Basic Auth. **Username** is your API token, **password** is empty. Tokens are managed under `System > Access Control > Tokens`. ## Errors | HTTP status | When it happens | |---------------------|--------------------------------------------------------------------------------| | `400 Bad Request` | Missing or malformed query/body parameter. | | `401 Unauthorized` | Missing or invalid credentials. | | `403 Forbidden` | Token lacks permission for this operation. | | `404 Not Found` | Target entity does not exist. | | `5xx` | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. | > **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly. ### Response **Status**: 204 No Content --- ## List Auth Providers **GET** `{{edgeUrl}}/auth/v2/providers` # List Auth Providers Returns every LDAP / Active Directory auth provider configured on the device. Bind credentials are masked. ## Endpoint ```http GET {{edgeUrl}}/auth/v2/providers ``` ## Authentication HTTP Basic Auth. **Username** is your API token, **password** is empty. Tokens are managed under `System > Access Control > Tokens`. ## Response `200 OK` -- `application/json`. Array of provider objects. Key fields: | Field | Type | Description | |------------------------|---------|----------------------------------------------------------------------------| | `id` | string | Provider UUID. | | `name` | string | Display name. | | `host` / `port` | mixed | LDAP server address. | | `tls` | boolean | Whether to use LDAPS. | | `bindDN` / `bindDNPassword` | string | Service account credentials (password masked). | | `groupSearchBaseDN` / `groupSearchScope` / `groupFilter` | string | Group lookup config. | | `groupAttr*` | string | Attribute names for group membership traversal. | | `tlsRootCA` | string | Optional PEM CA chain for TLS verification. | ## Errors | HTTP status | When it happens | |---------------------|--------------------------------------------------------------------------------| | `400 Bad Request` | Missing or malformed query/body parameter. | | `401 Unauthorized` | Missing or invalid credentials. | | `403 Forbidden` | Token lacks permission for this operation. | | `404 Not Found` | Target entity does not exist. | | `5xx` | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. | > **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly. ### Response **Status**: 200 OK ```json [ { "bindDN": "cn=Manager,dc=example,dc=com", "bindDNPassword": "*******", "groupAttrGroup": "member", "groupAttrName": "cn", "groupAttrUser": "DN", "groupFilter": "(&(objectClass=top)(objectClass=posixGroup))", "groupSearchBaseDN": "ou=Groups,dc=example,dc=com", "groupSearchScope": "sub", "host": "example.com", "id": "822a584e-09f9-46f7-a99c-52f3ea2a2dc3", "name": "Company LDAP", "port": 389, "tls": true, "tlsRootCA": "-----BEGIN CERTIFICATE-----SOMETHING HERE-----END CERTIFICATE-----", "type": "ldap2307", "userAttrFirstName": "givenName", "userAttrID": "uidNumber", "userAttrLastName": "sn", "userAttrUsername": "uid", "userFilter": "(&(objectClass=top)(objectClass=inetOrgPerson)(objectClass=posixAccount))", "userSearchBaseDN": "ou=People,dc=example,dc=com", "userSearchScope": "sub" } ] ``` --- ## Create New Auth Provider **POST** `{{edgeUrl}}/auth/v2/providers` # Create New Auth Provider Creates a new LDAP / Active Directory provider. Test with `Test Configuration` first to verify connectivity before persisting. ## Endpoint ```http POST {{edgeUrl}}/auth/v2/providers ``` ## Authentication HTTP Basic Auth. **Username** is your API token, **password** is empty. Tokens are managed under `System > Access Control > Tokens`. ## Request body The body carries the same fields as `List Auth Providers` returns (minus `id`), plus `groupsToRoles` which maps LDAP group DN to LE role name: ```json { "name": "Company LDAP", "host": "example.com", "port": 389, "tls": true, "bindDN": "cn=Manager,dc=example,dc=com", "bindDNPassword": "*******", "groupSearchBaseDN": "ou=Groups,dc=example,dc=com", "groupSearchScope": "sub", "groupFilter": "(&(objectClass=top)(objectClass=posixGroup))", "groupAttrName": "cn", "groupAttrGroup": "member", "groupAttrUser": "DN", "groupsToRoles": { "CN=loopedge-admins": "Administrator" }, "tlsRootCA": "-----BEGIN CERTIFICATE-----..." } ``` ## Errors | HTTP status | When it happens | |---------------------|--------------------------------------------------------------------------------| | `400 Bad Request` | Missing or malformed query/body parameter. | | `401 Unauthorized` | Missing or invalid credentials. | | `403 Forbidden` | Token lacks permission for this operation. | | `404 Not Found` | Target entity does not exist. | | `5xx` | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. | > **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly. ### Request Body ```json { "bindDN": "cn=Manager,dc=example,dc=com", "bindDNPassword": "*******", "groupAttrGroup": "member", "groupAttrName": "cn", "groupAttrUser": "DN", "groupFilter": "(&(objectClass=top)(objectClass=posixGroup))", "groupSearchBaseDN": "ou=Groups,dc=example,dc=com", "groupSearchScope": "sub", "groupsToRoles": { "Aut mollitia non consectetur error.": "Delectus aut." }, "host": "example.com", "name": "Company LDAP", "port": 389, "tls": true, "tlsRootCA": "-----BEGIN CERTIFICATE-----\nMIIGDjCCA/agAwIBAgIQNoJef7WkgZN+9tFza7k8pjANBgkqhkiG9w0BAQwFADCB\nhTELMAkGA1UEBhMCR0IxGzAZBgNVBAgTEkdyZWF0ZXIgTWFuY2hlc3RlcjEQMA4G\nADAdBgNVHSUEFjAUBggrBgEFBQcDAQYIKwYBBQUHAwIwGwYDVR0gBBQwEjAGBgRV\nHSAAMAgGBmeBDAECAjBMBgNVHR8ERTBDMEGgP6A9hjtodHRwOi8vY3JsLmNvbW9k\nb2NhLmNvbS9DT01PRE9SU0FDZXJ0aWZpY2F0aW9uQXV0aG9yaXR5LmNybDBxBggr\n...\n4J6ijvyxFnlcIdNFgZoMOWxtKNcl0rcRkND23m9e9Pqki2Z3ci+bkEAsUhJg+f+1\ncC6JmnkJiYEt7Fx4b4GH8fxV\n-----END CERTIFICATE-----", "type": "generic", "userAttrFirstName": "givenName", "userAttrID": "uidNumber", "userAttrLastName": "sn", "userAttrUsername": "uid", "userFilter": "(&(objectClass=top)(objectClass=inetOrgPerson)(objectClass=posixAccount))", "userSearchBaseDN": "ou=People,dc=example,dc=com", "userSearchScope": "sub" } ``` ### Response **Status**: 200 OK ```json { "bindDN": "cn=Manager,dc=example,dc=com", "bindDNPassword": "*******", "groupAttrGroup": "member", "groupAttrName": "cn", "groupAttrUser": "DN", "groupFilter": "(&(objectClass=top)(objectClass=posixGroup))", "groupSearchBaseDN": "ou=Groups,dc=example,dc=com", "groupSearchScope": "sub", "host": "example.com", "id": "2130913a-0060-4861-914b-4693a22132d6", "name": "Company LDAP", "port": 389, "tls": true, "tlsRootCA": "-----BEGIN CERTIFICATE-----\nMIIGDjCCA/agAwIBAgIQNoJef7WkgZN+9tFza7k8pjANBgkqhkiG9w0BAQwFADCB\nhTELMAkGA1UEBhMCR0IxGzAZBgNVBAgTEkdyZWF0ZXIgTWFuY2hlc3RlcjEQMA4G\nADAdBgNVHSUEFjAUBggrBgEFBQcDAQYIKwYBBQUHAwIwGwYDVR0gBBQwEjAGBgRV\nHSAAMAgGBmeBDAECAjBMBgNVHR8ERTBDMEGgP6A9hjtodHRwOi8vY3JsLmNvbW9k\nb2NhLmNvbS9DT01PRE9SU0FDZXJ0aWZpY2F0aW9uQXV0aG9yaXR5LmNybDBxBggr\n...\n4J6ijvyxFnlcIdNFgZoMOWxtKNcl0rcRkND23m9e9Pqki2Z3ci+bkEAsUhJg+f+1\ncC6JmnkJiYEt7Fx4b4GH8fxV\n-----END CERTIFICATE-----", "type": "generic", "userAttrFirstName": "givenName", "userAttrID": "uidNumber", "userAttrLastName": "sn", "userAttrUsername": "uid", "userFilter": "(&(objectClass=top)(objectClass=inetOrgPerson)(objectClass=posixAccount))", "userSearchBaseDN": "ou=People,dc=example,dc=com", "userSearchScope": "sub" } ``` --- ## Test Configuration **POST** `{{edgeUrl}}/auth/v2/providers/config/test` # Test Configuration Tests an LDAP / Active Directory configuration **without persisting** it. Returns success when the bind succeeds and a group search returns results. ## Endpoint ```http POST {{edgeUrl}}/auth/v2/providers/config/test ``` ## Authentication HTTP Basic Auth. **Username** is your API token, **password** is empty. Tokens are managed under `System > Access Control > Tokens`. ## Request body Same shape as `Create New Auth Provider`. ## Errors | HTTP status | When it happens | |---------------------|--------------------------------------------------------------------------------| | `400 Bad Request` | Missing or malformed query/body parameter. | | `401 Unauthorized` | Missing or invalid credentials. | | `403 Forbidden` | Token lacks permission for this operation. | | `404 Not Found` | Target entity does not exist. | | `5xx` | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. | > **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly. ### Request Body ```json { "bindDN": "cn=Manager,dc=example,dc=com", "bindDNPassword": "*******", "groupAttrGroup": "member", "groupAttrName": "cn", "groupAttrUser": "DN", "groupFilter": "(&(objectClass=top)(objectClass=posixGroup))", "groupSearchBaseDN": "ou=Groups,dc=example,dc=com", "groupSearchScope": "sub", "groupsToRoles": { "Aut mollitia non consectetur error.": "Delectus aut." }, "host": "example.com", "name": "Company LDAP", "port": 389, "tls": true, "tlsRootCA": "-----BEGIN CERTIFICATE-----\nMIIGDjCCA/agAwIBAgIQNoJef7WkgZN+9tFza7k8pjANBgkqhkiG9w0BAQwFADCB\nhTELMAkGA1UEBhMCR0IxGzAZBgNVBAgTEkdyZWF0ZXIgTWFuY2hlc3RlcjEQMA4G\nADAdBgNVHSUEFjAUBggrBgEFBQcDAQYIKwYBBQUHAwIwGwYDVR0gBBQwEjAGBgRV\nHSAAMAgGBmeBDAECAjBMBgNVHR8ERTBDMEGgP6A9hjtodHRwOi8vY3JsLmNvbW9k\nb2NhLmNvbS9DT01PRE9SU0FDZXJ0aWZpY2F0aW9uQXV0aG9yaXR5LmNybDBxBggr\n...\n4J6ijvyxFnlcIdNFgZoMOWxtKNcl0rcRkND23m9e9Pqki2Z3ci+bkEAsUhJg+f+1\ncC6JmnkJiYEt7Fx4b4GH8fxV\n-----END CERTIFICATE-----", "type": "generic", "userAttrFirstName": "givenName", "userAttrID": "uidNumber", "userAttrLastName": "sn", "userAttrUsername": "uid", "userFilter": "(&(objectClass=top)(objectClass=inetOrgPerson)(objectClass=posixAccount))", "userSearchBaseDN": "ou=People,dc=example,dc=com", "userSearchScope": "sub" } ``` --- ## Get Provider Details **GET** `{{edgeUrl}}/auth/v2/providers/{{auth_provider_id}}` # Get Provider Details Returns the configuration of one provider by UUID. Same shape as one element of `List Auth Providers`. ## Endpoint ```http GET {{edgeUrl}}/auth/v2/providers/{{auth_provider_id}} ``` ## Authentication HTTP Basic Auth. **Username** is your API token, **password** is empty. Tokens are managed under `System > Access Control > Tokens`. ## Errors | HTTP status | When it happens | |---------------------|--------------------------------------------------------------------------------| | `400 Bad Request` | Missing or malformed query/body parameter. | | `401 Unauthorized` | Missing or invalid credentials. | | `403 Forbidden` | Token lacks permission for this operation. | | `404 Not Found` | Target entity does not exist. | | `5xx` | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. | > **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly. ### Response **Status**: 200 OK ```json { "bindDN": "cn=Manager,dc=example,dc=com", "bindDNPassword": "*******", "groupAttrGroup": "member", "groupAttrName": "cn", "groupAttrUser": "DN", "groupFilter": "(&(objectClass=top)(objectClass=posixGroup))", "groupSearchBaseDN": "ou=Groups,dc=example,dc=com", "groupSearchScope": "sub", "host": "example.com", "id": "2130913a-0060-4861-914b-4693a22132d6", "name": "Company LDAP", "port": 389, "tls": true, "tlsRootCA": "-----BEGIN CERTIFICATE-----\nMIIGDjCCA/agAwIBAgIQNoJef7WkgZN+9tFza7k8pjANBgkqhkiG9w0BAQwFADCB\nhTELMAkGA1UEBhMCR0IxGzAZBgNVBAgTEkdyZWF0ZXIgTWFuY2hlc3RlcjEQMA4G\nADAdBgNVHSUEFjAUBggrBgEFBQcDAQYIKwYBBQUHAwIwGwYDVR0gBBQwEjAGBgRV\nHSAAMAgGBmeBDAECAjBMBgNVHR8ERTBDMEGgP6A9hjtodHRwOi8vY3JsLmNvbW9k\nb2NhLmNvbS9DT01PRE9SU0FDZXJ0aWZpY2F0aW9uQXV0aG9yaXR5LmNybDBxBggr\n...\n4J6ijvyxFnlcIdNFgZoMOWxtKNcl0rcRkND23m9e9Pqki2Z3ci+bkEAsUhJg+f+1\ncC6JmnkJiYEt7Fx4b4GH8fxV\n-----END CERTIFICATE-----", "type": "generic", "userAttrFirstName": "givenName", "userAttrID": "uidNumber", "userAttrLastName": "sn", "userAttrUsername": "uid", "userFilter": "(&(objectClass=top)(objectClass=inetOrgPerson)(objectClass=posixAccount))", "userSearchBaseDN": "ou=People,dc=example,dc=com", "userSearchScope": "sub" } ``` --- ## Update Provider **PUT** `{{edgeUrl}}/auth/v2/providers/{{auth_provider_id}}` # Update Provider Updates one provider in place. Send the full configuration; omitted fields are reset. ## Endpoint ```http PUT {{edgeUrl}}/auth/v2/providers/{{auth_provider_id}} ``` ## Authentication HTTP Basic Auth. **Username** is your API token, **password** is empty. Tokens are managed under `System > Access Control > Tokens`. ## Errors | HTTP status | When it happens | |---------------------|--------------------------------------------------------------------------------| | `400 Bad Request` | Missing or malformed query/body parameter. | | `401 Unauthorized` | Missing or invalid credentials. | | `403 Forbidden` | Token lacks permission for this operation. | | `404 Not Found` | Target entity does not exist. | | `5xx` | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. | > **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly. ### Request Body ```json { "bindDN": "cn=Manager,dc=example,dc=com", "bindDNPassword": "*******", "groupAttrGroup": "member", "groupAttrName": "cn", "groupAttrUser": "DN", "groupFilter": "(&(objectClass=top)(objectClass=posixGroup))", "groupSearchBaseDN": "ou=Groups,dc=example,dc=com", "groupSearchScope": "sub", "groupsToRoles": { "Aut mollitia non consectetur error.": "Delectus aut." }, "host": "example.com", "name": "Company LDAP", "port": 389, "tls": true, "tlsRootCA": "-----BEGIN CERTIFICATE-----\nMIIGDjCCA/agAwIBAgIQNoJef7WkgZN+9tFza7k8pjANBgkqhkiG9w0BAQwFADCB\nhTELMAkGA1UEBhMCR0IxGzAZBgNVBAgTEkdyZWF0ZXIgTWFuY2hlc3RlcjEQMA4G\nADAdBgNVHSUEFjAUBggrBgEFBQcDAQYIKwYBBQUHAwIwGwYDVR0gBBQwEjAGBgRV\nHSAAMAgGBmeBDAECAjBMBgNVHR8ERTBDMEGgP6A9hjtodHRwOi8vY3JsLmNvbW9k\nb2NhLmNvbS9DT01PRE9SU0FDZXJ0aWZpY2F0aW9uQXV0aG9yaXR5LmNybDBxBggr\n...\n4J6ijvyxFnlcIdNFgZoMOWxtKNcl0rcRkND23m9e9Pqki2Z3ci+bkEAsUhJg+f+1\ncC6JmnkJiYEt7Fx4b4GH8fxV\n-----END CERTIFICATE-----", "type": "generic", "userAttrFirstName": "givenName", "userAttrID": "uidNumber", "userAttrLastName": "sn", "userAttrUsername": "uid", "userFilter": "(&(objectClass=top)(objectClass=inetOrgPerson)(objectClass=posixAccount))", "userSearchBaseDN": "ou=People,dc=example,dc=com", "userSearchScope": "sub" } ``` --- ## List Provider User Groups **GET** `{{edgeUrl}}/auth/v2/providers/{{auth_provider_id}}/groups` # List Provider User Groups Lists the LDAP groups discovered by one provider and which LE role each is mapped to (`role`). Mappings come from the provider's `groupsToRoles` configuration. ## Endpoint ```http GET {{edgeUrl}}/auth/v2/providers/{{auth_provider_id}}/groups ``` ## Authentication HTTP Basic Auth. **Username** is your API token, **password** is empty. Tokens are managed under `System > Access Control > Tokens`. ## Response ```json [ { "dn": "CN=loopedge-observer,CN=Users,DC=l4d,DC=win", "id": "...", "name": "...", "role": "Viewer" } ] ``` ## Errors | HTTP status | When it happens | |---------------------|--------------------------------------------------------------------------------| | `400 Bad Request` | Missing or malformed query/body parameter. | | `401 Unauthorized` | Missing or invalid credentials. | | `403 Forbidden` | Token lacks permission for this operation. | | `404 Not Found` | Target entity does not exist. | | `5xx` | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. | > **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly. ### Response **Status**: 200 OK ```Text [ { "dn": "CN=loopedge-observer,CN=Users,DC=l4d,DC=win", "id": "822a584e-09f9-46f7-a99c-52f3ea2a2dc3", "name": "Et suscipit.", "role": "Molestiae occaecati aspernatur." }, { "dn": "CN=loopedge-observer,CN=Users,DC=l4d,DC=win", "id": "822a584e-09f9-46f7-a99c-52f3ea2a2dc3", "name": "Et suscipit.", "role": "Molestiae occaecati aspernatur." } ] ``` --- ## Unmap a Provider to User Group **DELETE** `{{edgeUrl}}/auth/v2/providers/{{auth_provider_id}}/groups/{{auth_provider_groupId}}` # Unmap a Provider to User Group Removes one provider-group -> LE-role mapping. The LDAP group remains in the provider's discovered list but no longer grants any LE role. ## Endpoint ```http DELETE {{edgeUrl}}/auth/v2/providers/{{auth_provider_id}}/groups/{{auth_provider_groupId}} ``` ## Authentication HTTP Basic Auth. **Username** is your API token, **password** is empty. Tokens are managed under `System > Access Control > Tokens`. ## Request body ```json { "roleName": "administrator" } ``` ## Errors | HTTP status | When it happens | |---------------------|--------------------------------------------------------------------------------| | `400 Bad Request` | Missing or malformed query/body parameter. | | `401 Unauthorized` | Missing or invalid credentials. | | `403 Forbidden` | Token lacks permission for this operation. | | `404 Not Found` | Target entity does not exist. | | `5xx` | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. | > **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly. ### Request Body ```json { "roleName": "administrator" } ``` --- ## Get Provider Status **GET** `{{edgeUrl}}/auth/v2/providers/{{auth_provider_id}}/status` # Get Provider Status Returns the current connection status of one provider. ## Endpoint ```http GET {{edgeUrl}}/auth/v2/providers/{{auth_provider_id}}/status ``` ## Authentication HTTP Basic Auth. **Username** is your API token, **password** is empty. Tokens are managed under `System > Access Control > Tokens`. ## Response ```json { "status": "OK" } ``` ## Errors | HTTP status | When it happens | |---------------------|--------------------------------------------------------------------------------| | `400 Bad Request` | Missing or malformed query/body parameter. | | `401 Unauthorized` | Missing or invalid credentials. | | `403 Forbidden` | Token lacks permission for this operation. | | `404 Not Found` | Target entity does not exist. | | `5xx` | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. | > **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly. ### Response **Status**: 200 OK ```json { "status": "OK" } ``` --- ## Delete Provider **DELETE** `{{edgeUrl}}/auth/v2/providers/{{auth_provider_id}}` # Delete Provider Removes an LDAP / Active Directory provider. Users who could only authenticate via this provider can no longer log in. ## Endpoint ```http DELETE {{edgeUrl}}/auth/v2/providers/{{auth_provider_id}} ``` ## Authentication HTTP Basic Auth. **Username** is your API token, **password** is empty. Tokens are managed under `System > Access Control > Tokens`. ## Errors | HTTP status | When it happens | |---------------------|--------------------------------------------------------------------------------| | `400 Bad Request` | Missing or malformed query/body parameter. | | `401 Unauthorized` | Missing or invalid credentials. | | `403 Forbidden` | Token lacks permission for this operation. | | `404 Not Found` | Target entity does not exist. | | `5xx` | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. | > **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly. ### Response **Status**: 204 No Content --- ## List of Possible Actions by User **GET** `{{edgeUrl}}/dm/dsmonitoring/actions/user` # List of Possible Actions by User Returns the legal `action` strings for the **user-level** disk-space threshold in `Device Management > Disk Space Policy`. Despite living under `Password Policy`, this is a disk-space helper. ## Endpoint ```http GET {{edgeUrl}}/dm/dsmonitoring/actions/user ``` ## Authentication HTTP Basic Auth. **Username** is your API token, **password** is empty. Tokens are managed under `System > Access Control > Tokens`. ## Response ```json [ { "alias": "none", "name": "None" }, { "alias": "warning", "name": "Warning" }, { "alias": "stopDataCollection", "name": "Stop data collection" } ] ``` ## Errors | HTTP status | When it happens | |---------------------|--------------------------------------------------------------------------------| | `400 Bad Request` | Missing or malformed query/body parameter. | | `401 Unauthorized` | Missing or invalid credentials. | | `403 Forbidden` | Token lacks permission for this operation. | | `404 Not Found` | Target entity does not exist. | | `5xx` | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. | > **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly. ### Response **Status**: 200 OK ```json [ { "alias": "none", "name": "None" }, { "alias": "warning", "name": "Warning" }, { "alias": "stopDataCollection", "name": "Stop data collection" } ] ``` --- ## List of Possible Actions by System **GET** `{{edgeUrl}}/dm/dsmonitoring/actions/system` # List of Possible Actions by System Returns the legal `action` strings for the **system-level** disk-space threshold (more severe than the user-level set). ## Endpoint ```http GET {{edgeUrl}}/dm/dsmonitoring/actions/system ``` ## Authentication HTTP Basic Auth. **Username** is your API token, **password** is empty. Tokens are managed under `System > Access Control > Tokens`. ## Response ```json [ { "alias": "stopDataCollection", "name": "Stop data collection" }, { "alias": "shutdown", "name": "Shutdown" } ] ``` ## Errors | HTTP status | When it happens | |---------------------|--------------------------------------------------------------------------------| | `400 Bad Request` | Missing or malformed query/body parameter. | | `401 Unauthorized` | Missing or invalid credentials. | | `403 Forbidden` | Token lacks permission for this operation. | | `404 Not Found` | Target entity does not exist. | | `5xx` | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. | > **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly. ### Response **Status**: 200 OK ```json [ { "alias": "stopDataCollection", "name": "Stop data collection" }, { "alias": "shutdown", "name": "Shutdown" } ] ``` --- ## Show Current or Default Password Policy **GET** `{{edgeUrl}}/auth/v2/password/policy/{{default}}` # Show Current or Default Password Policy Returns the password policy. The last path segment is a boolean: `true` returns the factory default, `false` returns the current (possibly customized) policy. ## Endpoint ```http GET {{edgeUrl}}/auth/v2/password/policy/{{default}} ``` ## Authentication HTTP Basic Auth. **Username** is your API token, **password** is empty. Tokens are managed under `System > Access Control > Tokens`. ## Path parameters | Location | Name | Required | Description | |----------|---------------|----------|----------------------------------------------------------------------| | Path | `{{default}}` | Yes | `true` for the factory default policy, `false` for the current one. | ## Response ```json { "genCharacterLength": 12, "maxCharacterLength": 256, "minCharacterLength": 8, "minDigits": 1, "minLowercaseChars": 1, "minSpecialChars": 1, "minUppercaseChars": 1, "specialChars": "~!@#$%^&*()_-{}[]|;:,.<>?/" } ``` | Field | Type | Description | |-------------------------|---------|-------------------------------------------------------------------| | `genCharacterLength` | integer | Length of server-generated passwords (e.g. FTP user create). | | `min/maxCharacterLength`| integer | Hard length bounds. | | `minDigits` / `minLowercaseChars` / `minSpecialChars` / `minUppercaseChars` | integer | Composition requirements. | | `specialChars` | string | Set of characters classified as "special". | ## Errors | HTTP status | When it happens | |---------------------|--------------------------------------------------------------------------------| | `400 Bad Request` | Missing or malformed query/body parameter. | | `401 Unauthorized` | Missing or invalid credentials. | | `403 Forbidden` | Token lacks permission for this operation. | | `404 Not Found` | Target entity does not exist. | | `5xx` | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. | > **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly. ### Response **Status**: 200 OK ```json { "genCharacterLength": 12, "maxCharacterLength": 256, "minCharacterLength": 8, "minDigits": 1, "minLowercaseChars": 1, "minSpecialChars": 1, "minUppercaseChars": 1, "specialChars": "~!@#$%^&*()_-{}[]|;:,.<>?/" } ``` --- ## Password Strength Checker **POST** `{{edgeUrl}}/auth/v2/password` # Password Strength Checker Evaluates whether a candidate password satisfies the current policy. Useful for previewing strength in a custom UI before submitting a `Change Password` request. ## Endpoint ```http POST {{edgeUrl}}/auth/v2/password ``` ## Authentication HTTP Basic Auth. **Username** is your API token, **password** is empty. Tokens are managed under `System > Access Control > Tokens`. ## Request body ```json { "password": "123" } ``` ## Response `200 OK` -- `application/json`. Reports `isSufficient` plus a per-requirement breakdown. ```json { "isSufficient": false, "requirements": { "length": { "actual": 3, "min": 8, "ok": false }, "lowercaseChars": { "actual": 0, "min": 1, "ok": false }, "specialChars": { "actual": 0, "min": 1, "ok": false }, "uppercaseChars": { "actual": 0, "min": 1, "ok": false } }, "score": 0 } ``` ## Errors | HTTP status | When it happens | |---------------------|--------------------------------------------------------------------------------| | `400 Bad Request` | Missing or malformed query/body parameter. | | `401 Unauthorized` | Missing or invalid credentials. | | `403 Forbidden` | Token lacks permission for this operation. | | `404 Not Found` | Target entity does not exist. | | `5xx` | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. | > **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly. ### Request Body ```json { "password": "123" } ``` ### Response **Status**: 200 OK ```json { "isSufficient": false, "requirements": { "length": { "actual": 3, "min": 8, "ok": false }, "lowercaseChars": { "actual": 0, "min": 1, "ok": false }, "specialChars": { "actual": 0, "min": 1, "ok": false }, "uppercaseChars": { "actual": 0, "min": 1, "ok": false } }, "score": 0 } ``` --- ## Change Password **PUT** `{{edgeUrl}}/auth/v2/password` # Change Password Changes the authenticated user's password. Subject to the policy returned by `Show Current or Default Password Policy`. ## Endpoint ```http PUT {{edgeUrl}}/auth/v2/password ``` ## Authentication HTTP Basic Auth. **Username** is your API token, **password** is empty. Tokens are managed under `System > Access Control > Tokens`. ## Request body ```json { "currentPassword": "************", "newPassword": "************" } ``` ## Errors | HTTP status | When it happens | |---------------------|--------------------------------------------------------------------------------| | `400 Bad Request` | Missing or malformed query/body parameter. | | `401 Unauthorized` | Missing or invalid credentials. | | `403 Forbidden` | Token lacks permission for this operation. | | `404 Not Found` | Target entity does not exist. | | `5xx` | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. | > **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly. ### Request Body ```json { "currentPassword": "************", "newPassword": "************" } ``` --- ## Update Non-Default Password Policy **PUT** `{{edgeUrl}}/auth/v2/password/policy` # Update Non-Default Password Policy Overrides the device's password policy. The non-default policy is persistent and applies to all subsequent password changes. ## Endpoint ```http PUT {{edgeUrl}}/auth/v2/password/policy ``` ## Authentication HTTP Basic Auth. **Username** is your API token, **password** is empty. Tokens are managed under `System > Access Control > Tokens`. ## Request body ```json { "genCharacterLength": 12, "maxCharacterLength": 20, "minCharacterLength": 8, "minDigits": 1, "minLowercaseChars": 1, "minSpecialChars": 1, "minUppercaseChars": 1, "specialChars": "!\"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~" } ``` ## Errors | HTTP status | When it happens | |---------------------|--------------------------------------------------------------------------------| | `400 Bad Request` | Missing or malformed query/body parameter. | | `401 Unauthorized` | Missing or invalid credentials. | | `403 Forbidden` | Token lacks permission for this operation. | | `404 Not Found` | Target entity does not exist. | | `5xx` | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. | > **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly. ### Request Body ```json { "genCharacterLength": 12, "maxCharacterLength": 20, "minCharacterLength": 8, "minDigits": 1, "minLowercaseChars": 1, "minSpecialChars": 1, "minUppercaseChars": 1, "specialChars": "!\"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~" } ``` --- ## Remove Non-Default Password Policy **DELETE** `{{edgeUrl}}/auth/v2/password/policy` # Remove Non-Default Password Policy Reverts to the factory-default password policy. ## Endpoint ```http DELETE {{edgeUrl}}/auth/v2/password/policy ``` ## Authentication HTTP Basic Auth. **Username** is your API token, **password** is empty. Tokens are managed under `System > Access Control > Tokens`. ## Errors | HTTP status | When it happens | |---------------------|--------------------------------------------------------------------------------| | `400 Bad Request` | Missing or malformed query/body parameter. | | `401 Unauthorized` | Missing or invalid credentials. | | `403 Forbidden` | Token lacks permission for this operation. | | `404 Not Found` | Target entity does not exist. | | `5xx` | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. | > **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly. --- ## Create OIDC Provider **POST** `{{edgeUrl}}/auth/v3/oidc/client` # Create OIDC Provider Creates a new OpenID Connect (OIDC) authentication provider. Supports Dynamic Client Registration (DCR) when the upstream provider exposes the standard DCR endpoint. ## Endpoint ```http POST {{edgeUrl}}/auth/v3/oidc/client ``` ## Authentication HTTP Basic Auth. **Username** is your API token, **password** is empty. Tokens are managed under `System > Access Control > Tokens`. ## Request body ```json { "providerName": "{{oidc_provider_name}}", "clientName": "{{oidc_client_name}}", "clientID": "{{oidc_client_id}}", "clientSecret": "{{oidc_client_secret}}", "redirectURI": "https://{{edgeUrl}}/auth/v3/oidc/callback", "url": "{{well_known_url}}", "dcr": { "accessToken": "{{oidc_access_token}}", "url": "{{oidc_dcr_url}}" }, "groups": ["default_admins_group"] } ``` | Field | Type | Required | Description | |-------------------|----------|----------|-----------------------------------------------------------------------------------| | `providerName` | string | Yes | Display name shown on the login page. | | `clientName` | string | Yes | OAuth client name. | | `clientID` | string | Yes | OAuth client ID issued by the provider. | | `clientSecret` | string | Yes | OAuth client secret. | | `redirectURI` | string | Yes | Must match a redirect URI registered with the provider. Default: `https:///auth/v3/oidc/callback`. | | `url` | string | Yes | The provider's `/.well-known/openid-configuration` URL. | | `dcr.url` / `dcr.accessToken` | string | No | Dynamic Client Registration endpoint + token. Omit for manual registration. | | `groups` | string[] | Yes | LE group IDs to grant successfully-authenticated users. | ## Errors | HTTP status | When it happens | |---------------------|--------------------------------------------------------------------------------| | `400 Bad Request` | Missing or malformed query/body parameter. | | `401 Unauthorized` | Missing or invalid credentials. | | `403 Forbidden` | Token lacks permission for this operation. | | `404 Not Found` | Target entity does not exist. | | `5xx` | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. | > **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly. ### Request Body ```json { "providerName": "{{oidc_provider_name}}", "clientName": "{{oidc_client_name}}", "clientID": "{{oidc_client_id}}", "clientSecret": "{{oidc_client_secret}}", "redirectURI": "https://{{edgeUrl}}/auth/v3/oidc/callback", "dcr": { "accessToken": "{{oidc_access_token}}", "url": "{{oidc_dcr_url}}" }, "url": "{{well_known_url}}", "groups": ["default_admins_group"] } ``` ### Response **Status**: 200 OK ```json { "id": "128073b0-e6e1-4892-80f2-e53b58c9f654", "providerName": "Provider", "clientName": "Client", "clientID": "*******", "clientSecret": "Litmus@1", "groups": [ "default_admins_group" ], "redirectURI": "https://{{edgeUrl}}/auth/v3/oidc/callback", "url": "http://{oidc_address}/realms/master/.well-known/openid-configuration" } ``` --- ## Get OIDC Provider **GET** `{{edgeUrl}}/auth/v3/oidc/client/{{oidc_id}}` # Get OIDC Provider Returns the configuration of one OIDC provider by UUID. `clientSecret` is masked. ## Endpoint ```http GET {{edgeUrl}}/auth/v3/oidc/client/{{oidc_id}} ``` ## Authentication HTTP Basic Auth. **Username** is your API token, **password** is empty. Tokens are managed under `System > Access Control > Tokens`. ## Errors | HTTP status | When it happens | |---------------------|--------------------------------------------------------------------------------| | `400 Bad Request` | Missing or malformed query/body parameter. | | `401 Unauthorized` | Missing or invalid credentials. | | `403 Forbidden` | Token lacks permission for this operation. | | `404 Not Found` | Target entity does not exist. | | `5xx` | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. | > **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly. ### Response **Status**: 200 OK ```json { "id": "254d0e6f-39a3-4863-aaf3-bf35662b0ab6", "providerName": "Provider", "clientName": "Client", "clientID": "admin", "clientSecret": "*******", "groups": [ "default_admins_group" ], "redirectURI": "https://{{edgeUrl}}/auth/v3/oidc/callback", "url": "{{well_known_url}}" } ``` --- ## Update OIDC Provider **PATCH** `{{edgeUrl}}/auth/v3/oidc/client/{{oidc_id}}` # Update OIDC Provider Updates an OIDC provider's configuration. Uses HTTP `PATCH` -- only fields present in the body are changed. ## Endpoint ```http PATCH {{edgeUrl}}/auth/v3/oidc/client/{{oidc_id}} ``` ## Authentication HTTP Basic Auth. **Username** is your API token, **password** is empty. Tokens are managed under `System > Access Control > Tokens`. ## Request body Same shape as `Create OIDC Provider`. Include only fields you want to update. ## Errors | HTTP status | When it happens | |---------------------|--------------------------------------------------------------------------------| | `400 Bad Request` | Missing or malformed query/body parameter. | | `401 Unauthorized` | Missing or invalid credentials. | | `403 Forbidden` | Token lacks permission for this operation. | | `404 Not Found` | Target entity does not exist. | | `5xx` | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. | > **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly. ### Request Body ```json { "providerName": "{{oidc_provider_name}}", "clientName": "{{oidc_client_name}}", "clientID": "{{oidc_client_id}}", "clientSecret": "{{oidc_client_secret}}", "redirectURI": "https://{{edgeUrl}}/auth/v3/oidc/callback", "url": "{{well_known_url}}", "groups": [ "default_admins_group" ] } ``` ### Response **Status**: 200 OK ```json { "id": "254d0e6f-39a3-4863-aaf3-bf35662b0ab6", "providerName": "Provider2", "clientName": "Client", "clientID": "admin", "clientSecret": "******", "groups": [ "default_admins_group" ], "redirectURI": "https://{{edgeUrl}}/auth/v3/oidc/callback", "url": "http://{oidc_address}/realms/master/.well-known/openid-configuration" } ``` --- ## Update OIDC Provider Copy **PATCH** `{{edgeUrl}}/auth/v3/oidc/client/{{oidc_id}}` # Update OIDC Provider Copy Duplicate of `Update OIDC Provider` in the Postman collection (same URL, same body shape, same method). Prefer the original; this entry exists for historical reasons. ## Endpoint ```http PATCH {{edgeUrl}}/auth/v3/oidc/client/{{oidc_id}} ``` ## Authentication HTTP Basic Auth. **Username** is your API token, **password** is empty. Tokens are managed under `System > Access Control > Tokens`. ## Errors | HTTP status | When it happens | |---------------------|--------------------------------------------------------------------------------| | `400 Bad Request` | Missing or malformed query/body parameter. | | `401 Unauthorized` | Missing or invalid credentials. | | `403 Forbidden` | Token lacks permission for this operation. | | `404 Not Found` | Target entity does not exist. | | `5xx` | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. | > **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly. ### Request Body ```json { "providerName": "{{oidc_provider_name}}", "clientName": "{{oidc_client_name}}", "clientID": "{{oidc_client_id}}", "clientSecret": "{{oidc_client_secret}}", "redirectURI": "https://{{edgeUrl}}/auth/v3/oidc/callback", "url": "{{well_known_url}}", "groups": [ "default_admins_group" ] } ``` ### Response **Status**: 200 OK ```json { "id": "254d0e6f-39a3-4863-aaf3-bf35662b0ab6", "providerName": "Provider2", "clientName": "Client", "clientID": "admin", "clientSecret": "******", "groups": [ "default_admins_group" ], "redirectURI": "https://{{edgeUrl}}/auth/v3/oidc/callback", "url": "http://{oidc_address}/realms/master/.well-known/openid-configuration" } ``` --- ## List OIDC Providers **GET** `{{edgeUrl}}/auth/v3/oidc/client` # List OIDC Providers Returns every configured OIDC provider. ## Endpoint ```http GET {{edgeUrl}}/auth/v3/oidc/client ``` ## Authentication HTTP Basic Auth. **Username** is your API token, **password** is empty. Tokens are managed under `System > Access Control > Tokens`. ## Errors | HTTP status | When it happens | |---------------------|--------------------------------------------------------------------------------| | `400 Bad Request` | Missing or malformed query/body parameter. | | `401 Unauthorized` | Missing or invalid credentials. | | `403 Forbidden` | Token lacks permission for this operation. | | `404 Not Found` | Target entity does not exist. | | `5xx` | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. | > **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly. ### Response **Status**: 200 OK ```json [ { "id": "254d0e6f-39a3-4863-aaf3-bf35662b0ab6", "clientName": "Client", "clientID": "admin", "groups": [ "default_admins_group" ], "providerName": "Provider", "redirectURI": "https://{{edgeUrl}}/auth/v3/oidc/callback", "url": "http://{oidc_url}/realms/master/.well-known/openid-configuration" } ] ``` --- ## Delete OIDC Provider **DELETE** `{{edgeUrl}}/auth/v3/oidc/client/{{oidc_id}}` # Delete OIDC Provider Deletes an OIDC provider. Users who could only authenticate via this provider can no longer log in. ## Endpoint ```http DELETE {{edgeUrl}}/auth/v3/oidc/client/{{oidc_id}} ``` ## Authentication HTTP Basic Auth. **Username** is your API token, **password** is empty. Tokens are managed under `System > Access Control > Tokens`. ## Response `204 No Content` on success. ## Errors | HTTP status | When it happens | |---------------------|--------------------------------------------------------------------------------| | `400 Bad Request` | Missing or malformed query/body parameter. | | `401 Unauthorized` | Missing or invalid credentials. | | `403 Forbidden` | Token lacks permission for this operation. | | `404 Not Found` | Target entity does not exist. | | `5xx` | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. | > **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly. ### Response **Status**: 204 No Content ---