# 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 ```json { "groupId": "814b108c-dbb0-4640-9018-6577c4540e16", "groupName": "custom-group", "isSystem": false, "isAdmin": false, "roles": null, "users": 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 { "groupId": "814b108c-dbb0-4640-9018-6577c4540e16", "groupName": "custom-group", "isSystem": false, "isAdmin": false, "roles": null, "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 --- ## 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 | |--------------------------|---------|-------------------------------------------------------------------| | `username` | string | Login name. | | `firstName` / `lastName` | string | Display name. | | `disabled` | boolean | `true` when the account is disabled. | | `mustChangePassword` | boolean | `true` if the user must change password on next login. | | `eulaAcceptedTs` | integer | Timestamp when the user accepted the EULA; absent if not accepted. | ## 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 [ { "disabled": false, "firstName": "System", "lastName": "Administrator", "mustChangePassword": false, "username": "admin" }, { "disabled": false, "eulaAcceptedTs": 2619724477700016600, "firstName": "John", "isAdmin": false, "lastName": "Carter", "mustChangePassword": false, "username": "jcarter3" } ] ``` --- ## 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=true/false}` # Show Current or Default Password Policy Returns the password policy. Pass `default=true` (path parameter) to get the factory default; `default=false` returns the current (possibly customized) policy. ## Endpoint ```http GET {{edgeUrl}}/auth/v2/password/policy/{default=true/false} ``` ## Authentication HTTP Basic Auth. **Username** is your API token, **password** is empty. Tokens are managed under `System > Access Control > Tokens`. ## 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 ---