Litmus Edge 4.4.x - System: Access Control

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

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

[
  { "id": "default_admin_role",  "name": "Administrator", "system": true },
  { "id": "default_viewer_role", "name": "Viewer",        "system": true }
]

Errors

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

[
    {
        "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

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

{
  "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

{ "id": "731afed4-7a94-47f9-ae93-205ad5b047f8" }

Errors

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

{
  "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

{
    "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

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

Request body

Same shape as Add New Role.

Errors

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

{
  "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

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

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 Permissions

GET {{edgeUrl}}/auth/v3/permissions

List Permissions

Every permission a role can grant, grouped by the service (component) it applies to. The web UI builds the role editor from this list; use it to find valid values before Add New Role or Update User Role.

Endpoint

GET {{edgeUrl}}/auth/v3/permissions

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. An array with one entry per component:

The order of components and of permissions within a component is not stable between calls.

Errors

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

[
    {
        "component": {
            "id": "cc",
            "label": "Integrations",
            "desc": "Integrations."
        },
        "permissions": [
            "Modify",
            "View"
        ]
    },
    {
        "component": {
            "id": "css",
            "label": "Cloud Storage Sync",
            "desc": "Cloud Storage Sync sync data between local mounted directories and different cloud storage providers."
        },
        "permissions": [
            "Modify",
            "View"
        ]
    },
    {
        "component": {
            "id": "flows",
            "label": "Flows Manager",
            "desc": "Flows Manager."
        },
        "permissions": [
            "View",
            "Modify"
        ]
    },
    {
        "component": {
            "id": "dl",
            "label": "Downloads",
            "desc": "Downloads."
        },
        "permissions": [
            "View"
        ]
    },
    {
        "component": {
            "id": "dt",
            "label": "Digital Twin",
            "desc": "Digital Twin is a service for managing virtual models designed to accurately reflect physical objects."
        },
        "permissions": [
            "Modify",
            "View"
        ]
    },
    {
        "component": {
            "id": "events",
            "label": "Events",
            "desc": "Events allows viewing of system events."
        },
        "permissions": [
            "Modify",
            "View"
        ]
    },
    {
        "component": {
            "id": "ftp",
            "label": "FTP Server",
            "desc": "Internal FTP server."
        },
        "permissions": [
            "Modify",
            "View"
        ]
    },
    {
        "component": {
            "id": "lic",
            "label": "Licensing",
            "desc": "Licensing component provides license management functionality."
        },
        "permissions": [
            "Modify"
        ]
    },
    {
        "component": {
            "id": "stats",
            "label": "DataHub",
            "desc": "Stats component manages historic data."
        },
        "permissions": [
            "Modify",
            "View"
        ]
    },
    {
        "component": {
            "id": "dh",
            "label": "DeviceHub",
            "desc": "Device Hub is responsible for data acquisition from equipment."
        },
        "permissions": [
            "View",
            "ViewDevices",
            "ViewDrivers",
            "ViewTags",
            "Modify",
            "ModifyDevices",
            "ModifyTags"
        ]
    },
    {
        "component": {
            "id": "mp",
            "label": "Marketplace",
            "desc": "Marketplace component manages execution environment for marketplace application."
        },
        "permissions": [
            "Update",
            "View",
            "Create",
            "Delete",
            "Modify",
            "ModifyPrivileged"
        ]
    },
    {
        "component": {
            "id": "nd",
            "label": "Network Discovery",
            "desc": "Network Discovery allows scanning local networks for connected devices."
        },
        "permissions": [
            "Modify",
            "View"
        ]
    },
    {
        "component": {
            "id": "nwutil",
            "label": "Network Util",
            "desc": "Network tools."
        },
        "permissions": [
            "Modify",
            "View"
        ]
    },
    {
        "component": {
            "id": "opcua",
            "label": "OPCUA Server",
            "desc": "OPCUA server."
        },
        "permissions": [
            "Modify",
            "View"
        ]
    },
    {
        "component": {
            "id": "access",
            "label": "Access",
            "desc": "Access provides access to data from external systems."
        },
        "permissions": [
            "View",
            "Modify"
        ]
    },
    {
        "component": {
            "id": "auth",
            "label": "Auth",
            "desc": "Authentication and Authorization component."
        },
        "permissions": [
            "Modify"
        ]
    },
    {
        "component": {
            "id": "dm",
            "label": "Device Management",
            "desc": "Device Management."
        },
        "permissions": [
            "Modify"
        ]
    },
    {
        "component": {
            "id": "support",
            "label": "Support Bundle",
            "desc": "Support Bundle."
        },
        "permissions": [
            "Modify"
        ]
    },
    {
        "component": {
            "id": "sysinfo",
            "label": "System Info",
            "desc": "System Info component reports system information and performance."
        },
        "permissions": [
            "Modify"
        ]
    },
    {
        "component": {
            "id": "analytics",
            "label": "Analytics",
            "desc": "Analytics."
        },
        "permissions": [
            "Modify",
            "View"
        ]
    }
]

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

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

[
  { "groupId": "default_admins_group",  "groupName": "Administrators", "isSystem": true },
  { "groupId": "default_viewers_group", "groupName": "Viewers",        "isSystem": true }
]

Errors

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

[
    {
        "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

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

{ "group": { "groupName": "custom-group" } }

Response

{ "groupId": "814b108c-dbb0-4640-9018-6577c4540e16" }

Errors

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

{
  "group": {
    "groupName": "custom-group"
  }
}

Response

Status: 200 OK

{
    "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

GET {{edgeUrl}}/auth/v3/groups/{{user-group}}

Authentication

HTTP Basic Auth. Username is your API token, password is empty. Tokens are managed under System > Access Control > Tokens.

Response

roles and users are null (not []) while the group is empty. Once populated, each entry carries both its ID and its display name:

{
  "groupId": "default_viewers_group",
  "groupName": "Viewers",
  "isSystem": true,
  "isAdmin": false,
  "roles": [
    { "roleId": "default_viewer_role", "roleName": "Viewer" }
  ],
  "users": null
}

Use Assign Roles to Group to change roles[] and Add Users to Group to change membership.

Errors

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

{
    "groupId": "default_viewers_group",
    "groupName": "Viewers",
    "isSystem": true,
    "isAdmin": false,
    "roles": [
        {
            "roleId": "default_viewer_role",
            "roleName": "Viewer"
        }
    ],
    "users": null
}

Add Users to Group

PUT {{edgeUrl}}/auth/v3/users/{{user-id}}/groups

Add Users to Group

Assigns one user to one or more groups. The path identifies the user; the body lists the groups to add.

Endpoint

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

Request body

{ "groups": ["{{user-group}}"] }

Errors

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

{
    "groups": [
        "{{user-group}}"
    ]
}

Response

Status: 204 No Content

Assign Roles to Group

PUT {{edgeUrl}}/auth/v3/groups/{{user-group}}/roles

Assign Roles to Group

Replaces the set of roles attached to a group. The path identifies the group; the body lists the role IDs it should hold.

This is a replace, not a merge: the roles array you send becomes the group's complete role set. Send the full list every time, and send an empty array to strip every role from the group.

Members of the group inherit the permissions of every role listed here. Use Get User Roles to look up the role IDs, and Get User Group Details to read back the result.

Endpoint

PUT {{edgeUrl}}/auth/v3/groups/{{user-group}}/roles

Authentication

HTTP Basic Auth. Username is your API token, password is empty. Tokens are managed under System > Access Control > Tokens.

Path parameters

Request body

{ "roles": ["default_viewer_role"] }

Response

204 No Content on success. The endpoint returns no body.

This endpoint resolves the caller's own user account before it applies the change. A bare API-credential token that is not bound to a user is rejected with 401 and {"error":{"Msg":"token doesn't contain a valid user id"}}. Call it with a user-bound session token.

Errors

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

{
    "roles": [
        "{{system-user-role-id}}"
    ]
}

Response

Status: 204 No Content

Update Group Name

PUT {{edgeUrl}}/auth/v3/groups/{{user-group}}

Update Group Name

Renames an existing group. The group ID is preserved.

Endpoint

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

{ "group": { "groupName": "custom-group-1" } }

Errors

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

{
  "group": {
    "groupName": "custom-group-1"
  }
}

Response

Status: 204 No Content

Delete User Group

DELETE {{edgeUrl}}/auth/v3/groups/{{user-group}}

Delete User Group

Deletes a user group. It is the call the web UI makes when you remove a group.

Endpoint

DELETE {{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.

Needs a user session token. An API token (Basic auth) is rejected with 401 {"error":{"Msg":"token doesn't contain a valid user id","MsgCode":""}}. Sign in as an administrator with POST {{edgeUrl}}/auth/v2/login (body {"username": "...", "password": "...", "providerId": "00000000-0000-0000-0000-000000000000"}, no Authorization header) and send the returned jwtAccess as Authorization: Bearer <jwtAccess>. Groups created with an API token therefore cannot be removed with that same token.

Path parameters

Response

204 No Content on success (verified on LE 4.0.x with a bearer token). An unknown group ID returns 404 with {"error":{"Msg":"data not found","MsgCode":""}}.

Errors

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.

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

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

eulaAcceptedTs, createdAt and modifiedAt are RFC 3339 strings (for example "2025-07-14T12:21:22-07:00"), not numeric timestamps. The offset is the device's local timezone, so do not assume a Z suffix.

Response example

[
  {
    "userId": "f5ed6b65-746f-4933-9bc6-0c617818f09b",
    "username": "admin",
    "firstName": "System",
    "lastName": "Administrator",
    "mustChangePassword": false,
    "mfaEnabled": false,
    "disabled": false,
    "isAdmin": true,
    "eulaAcceptedTs": "2025-07-14T12:21:22-07:00",
    "external": false,
    "createdAt": "2026-02-19T11:41:39-08:00",
    "modifiedAt": "2026-02-19T11:41:39-08:00"
  }
]

Errors

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

[
    {
        "userId": "f5ed6b65-746f-4933-9bc6-0c617818f09b",
        "username": "admin",
        "firstName": "System",
        "lastName": "Administrator",
        "mustChangePassword": false,
        "mfaEnabled": false,
        "disabled": false,
        "isAdmin": true,
        "eulaAcceptedTs": "2025-07-14T12:21:22-07:00",
        "external": false,
        "createdAt": "2026-02-19T11:41:39-08:00",
        "modifiedAt": "2026-02-19T11:41:39-08:00"
    },
    {
        "userId": "8c0752a5-c343-4fac-b9e8-aa0b5e876826",
        "username": "jcarter3",
        "firstName": "John",
        "lastName": "Carter",
        "mustChangePassword": false,
        "mfaEnabled": false,
        "disabled": false,
        "isAdmin": false,
        "eulaAcceptedTs": "2026-08-13T13:52:43Z",
        "external": false,
        "createdAt": "2026-08-01T09:14:02-07:00",
        "modifiedAt": "2026-08-13T13:52:43Z"
    }
]

Create an User

POST {{edgeUrl}}/auth/v3/users

Create an User

Creates a new local user. The password is set at create time; mustChangePassword: true forces the user to choose a new one at first login.

Endpoint

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.

Assign a group before the user can sign in. This call creates the user with no groups, and any groups / groupIds field in the body (top level or inside user) is ignored. Until a group is set, sign-in fails with 403 {"msg":"user has no groups assigned"}. Follow the create with Groups > Add Users to Group (PUT {{edgeUrl}}/auth/v3/users/{{user-id}}/groups with {"groups": ["<groupId>"]}), as the web UI does. Verified on LE 4.0.x.

Request body

{
  "user": {
    "firstName": "John",
    "lastName": "Carter",
    "username": "jcarter3",
    "mustChangePassword": true,
    "password": "Litmus@1",
    "passwordConfirmation": "Litmus@1"
  }
}

Response

200 OK -- application/json. The new user's ID only; use it as {{user-id}} in Add Users to Group, Get User Details, Update an User and Remove an User.

{ "userId": "e2253950-b9dc-4c39-ae5f-dd75ecad76d8" }

Errors

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

{
    "user": {
        "firstName": "John",
        "lastName": "Carter",
        "username": "jcarter3",
        "mustChangePassword": true,
        "password": "Litmus@1",
        "passwordConfirmation": "Litmus@1"
    }
}

Response

Status: 200 OK

{
    "userId": "e2253950-b9dc-4c39-ae5f-dd75ecad76d8"
}

Update an User

PUT {{edgeUrl}}/auth/v3/users/{{user-id}}

Update an User

Updates a local user, addressed by user ID. This replaces the earlier PUT /auth/v2/users/{username} example, which is not served on LE 4.0.x or later (the route answers 404 with an empty body). It is the call the web UI makes from the user edit dialog and from the enable / disable toggle.

Endpoint

PUT {{edgeUrl}}/auth/v3/users/{{user-id}}

Authentication

HTTP Basic Auth. Username is your API token, password is empty. Tokens are managed under System > Access Control > Tokens.

Path parameters

Request body

The user record wrapped in a user object. Send the whole record as returned by Get User Details with your changes applied; to disable an account, flip disabled. Add password and passwordConfirmation only when changing the password.

{
  "user": {
    "userId": "{{user-id}}",
    "username": "jcarter3",
    "firstName": "John",
    "lastName": "Carter",
    "mustChangePassword": false,
    "disabled": false
  }
}

Group membership is not changed by this call. Set it with Groups > Add Users to Group (PUT /auth/v3/users/{{user-id}}/groups), which is what the web UI does after saving the user.

Response

204 No Content on success, with an empty body; read the record back with Get User Details. An unknown {{user-id}} returns 404 with {"error":{"Msg":"data not found","MsgCode":""}}. Works with an API token (verified on LE 4.0.x).

Errors

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

{
    "user": {
        "userId": "{{user-id}}",
        "username": "jcarter3",
        "firstName": "John",
        "lastName": "Carter",
        "mustChangePassword": false,
        "disabled": false
    }
}

Remove an User

DELETE {{edgeUrl}}/auth/v3/users/{{user-id}}

Remove an User

Deletes a local user, addressed by user ID. This replaces the earlier DELETE /auth/v2/users/{username} example, which is not served on LE 4.0.x or later (the route answers 404 with an empty body). It is the call the web UI makes when you remove a user.

Endpoint

DELETE {{edgeUrl}}/auth/v3/users/{{user-id}}

Authentication

HTTP Basic Auth. Username is your API token, password is empty. Tokens are managed under System > Access Control > Tokens.

Path parameters

Response

204 No Content on success, with an empty body; read the record back with Get User Details. An unknown {{user-id}} returns 404 with {"error":{"Msg":"data not found","MsgCode":""}}. Works with an API token (verified on LE 4.0.x).

Errors

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.

Get User Details

GET {{edgeUrl}}/auth/v3/users/{{user-id}}

Get User Details

Full detail for one user, by user ID. Use List Users to obtain the userId.

Endpoint

GET {{edgeUrl}}/auth/v3/users/{{user-id}}

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.

external tells a locally managed account apart from one projected from LDAP, AD or OIDC. An unknown ID returns 404 with {"error":{"Msg":"data not found","MsgCode":""}}.

Errors

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

{
    "userId": "f5ed6b65-746f-4933-9bc6-0c617818f09b",
    "username": "admin",
    "firstName": "System",
    "lastName": "Administrator",
    "mustChangePassword": false,
    "mfaEnabled": false,
    "disabled": false,
    "isAdmin": true,
    "eulaAcceptedTs": "2025-07-14T12:21:22-07:00",
    "roles": [
        {
            "id": "default_admin_role",
            "name": "Administrator"
        }
    ],
    "external": false,
    "createdAt": "2026-02-19T11:41:39-08:00",
    "modifiedAt": "2026-02-19T11:41:39-08:00"
}

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

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

[ { "userId": "admin", "username": "admin", "firstName": "System", "lastName": "Administrator" } ]

Errors

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

[
    {
        "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

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

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

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

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 NATS Proxy State

GET {{edgeUrl}}/access/proxy/state

Get NATS Proxy State

Whether the NATS proxy is enabled. Pairs with Enable NATS Proxy and Disable NATS Proxy.

Endpoint

GET {{edgeUrl}}/access/proxy/state

Authentication

HTTP Basic Auth. Username is your API token, password is empty. Tokens are managed under System > Access Control > Tokens.

Parameters

None.

Response

200 OK -- application/json. A bare JSON string: "enabled" or "disabled".

"enabled"

Errors

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

enabled

Get NATS Access Configuration

POST {{edgeUrl}}/access/v2

Get NATS Access Configuration

Returns the whole Access configuration in one call: whether the NATS proxy is on, the leafnode mode with its leaf and hub settings, and the state of the service CA. The web UI loads it for the NATS access page.

Part of the Access service GraphQL API at /access/v2, which manages the device's NATS proxy and NATS leafnode links (this device as a leaf of a remote hub, as a hub for remote leafs, or both). For connecting a NATS client to the device, see the How-To: Authenticate a NATS / DataHub Client section.

Endpoint

POST {{edgeUrl}}/access/v2

Authentication

HTTP Basic Auth. Username is your API token, password is empty. The same token is valid across /devicehub/v2, /analytics/v2, /cc, /opcua, and the other LE services.

Query

query AccessNATSConfig {
  accessNATSConfig {
    proxyEnabled
    leafnodeConfig {
      mode
      leafSettings {
        streamConfigurations { accountName connectUrl hostname token topics tlsEnabled createdAt updatedAt }
      }
      hubSettings {
        listenAddress
        listenPort
        accounts { name token hostname enabled topicPrefix topics password createdAt updatedAt }
        tlsEnabled
      }
    }
    serviceCAStatus { status daysUntilExpiry statusMessage }
  }
}

No variables.

Response

data.accessNATSConfig:

Sensitive: hub accounts are returned with their token and password in clear text. Treat the response as a secret. The example below comes from a device in LEAF mode with no links, so it shows none.

Errors

GraphQL endpoints return 200 OK even on logical errors. Inspect the errors array in the response body:

{ "errors": [ { "message": "...", "path": ["..."], "extensions": { "code": "..." } } ] }

A non-200 HTTP response means DeviceHub itself is unreachable. See Dashboard > DeviceHub Status.

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

GraphQL Query

query AccessNATSConfig {
  accessNATSConfig {
    proxyEnabled
    leafnodeConfig {
      mode
      leafSettings {
        streamConfigurations { accountName connectUrl hostname token topics tlsEnabled createdAt updatedAt }
      }
      hubSettings {
        listenAddress
        listenPort
        accounts { name token hostname enabled topicPrefix topics password createdAt updatedAt }
        tlsEnabled
      }
    }
    serviceCAStatus { status daysUntilExpiry statusMessage }
  }
}

Response

Status: 200 OK

{
    "data": {
        "accessNATSConfig": {
            "proxyEnabled": true,
            "leafnodeConfig": {
                "mode": "LEAF",
                "leafSettings": {
                    "streamConfigurations": []
                },
                "hubSettings": null
            },
            "serviceCAStatus": {
                "status": "VALID",
                "daysUntilExpiry": 3415,
                "statusMessage": "Valid"
            }
        }
    }
}

Get Leafnode Status

POST {{edgeUrl}}/access/v2

Get Leafnode Status

Reports the state of the NATS leafnode feature and whether pending configuration needs a NATS reload or restart to take effect.

Part of the Access service GraphQL API at /access/v2, which manages the device's NATS proxy and NATS leafnode links (this device as a leaf of a remote hub, as a hub for remote leafs, or both). For connecting a NATS client to the device, see the How-To: Authenticate a NATS / DataHub Client section.

Endpoint

POST {{edgeUrl}}/access/v2

Authentication

HTTP Basic Auth. Username is your API token, password is empty. The same token is valid across /devicehub/v2, /analytics/v2, /cc, /opcua, and the other LE services.

Query

query LeafNodeStatus {
  leafNodeStatus {
    status
    changeType
    natsHealthy
    message
    backupExists
    backupTimestamp
    lastAppliedAt
    configMatchesDB
    validationErrors
    restartNeeded
    reloadRequired
  }
}

No variables.

Response

data.leafNodeStatus:

Errors

GraphQL endpoints return 200 OK even on logical errors. Inspect the errors array in the response body:

{ "errors": [ { "message": "...", "path": ["..."], "extensions": { "code": "..." } } ] }

A non-200 HTTP response means DeviceHub itself is unreachable. See Dashboard > DeviceHub Status.

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

GraphQL Query

query LeafNodeStatus {
  leafNodeStatus {
    status
    changeType
    natsHealthy
    message
    backupExists
    backupTimestamp
    lastAppliedAt
    configMatchesDB
    validationErrors
    restartNeeded
    reloadRequired
  }
}

Response

Status: 200 OK

{
    "data": {
        "leafNodeStatus": {
            "status": "NOT_CONNECTED",
            "changeType": "RESTART",
            "natsHealthy": true,
            "message": "LeafNode feature is disabled (NATS restart required to enable)",
            "backupExists": true,
            "backupTimestamp": "2026-03-17T15:28:44.07609656-07:00",
            "lastAppliedAt": "2026-03-17T15:28:44.298380235-07:00",
            "configMatchesDB": false,
            "validationErrors": [],
            "restartNeeded": true,
            "reloadRequired": false
        }
    }
}

List Stream Configurations

POST {{edgeUrl}}/access/v2

List Stream Configurations

Lists the links this device holds to remote NATS hubs as a leaf. Each link is created from a token issued by the hub.

Part of the Access service GraphQL API at /access/v2, which manages the device's NATS proxy and NATS leafnode links (this device as a leaf of a remote hub, as a hub for remote leafs, or both). For connecting a NATS client to the device, see the How-To: Authenticate a NATS / DataHub Client section.

Endpoint

POST {{edgeUrl}}/access/v2

Authentication

HTTP Basic Auth. Username is your API token, password is empty. The same token is valid across /devicehub/v2, /analytics/v2, /cc, /opcua, and the other LE services.

Query

query ListStreamConfigurations {
  listStreamConfigurations { accountName connectUrl hostname token topics tlsEnabled createdAt updatedAt }
}

No variables.

Response

data.listStreamConfigurations is a list (empty when the device has no links):

Errors

GraphQL endpoints return 200 OK even on logical errors. Inspect the errors array in the response body:

{ "errors": [ { "message": "...", "path": ["..."], "extensions": { "code": "..." } } ] }

A non-200 HTTP response means DeviceHub itself is unreachable. See Dashboard > DeviceHub Status.

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

GraphQL Query

query ListStreamConfigurations {
  listStreamConfigurations { accountName connectUrl hostname token topics tlsEnabled createdAt updatedAt }
}

Response

Status: 200 OK

{
    "data": {
        "listStreamConfigurations": []
    }
}

Get Leafnode Service CA

POST {{edgeUrl}}/access/v2

Get Leafnode Service CA

Returns the device's leafnode service CA certificate and its status. Remote leafs install this certificate to trust the device when it acts as a hub. The web UI uses it for the CA download button.

Part of the Access service GraphQL API at /access/v2, which manages the device's NATS proxy and NATS leafnode links (this device as a leaf of a remote hub, as a hub for remote leafs, or both). For connecting a NATS client to the device, see the How-To: Authenticate a NATS / DataHub Client section.

Endpoint

POST {{edgeUrl}}/access/v2

Authentication

HTTP Basic Auth. Username is your API token, password is empty. The same token is valid across /devicehub/v2, /analytics/v2, /cc, /opcua, and the other LE services.

Query

query LeafnodeServiceCA {
  leafnodeServiceCA { certificatePEM status daysUntilExpiry statusMessage affectedHubAccounts fingerprint subject }
}

No variables.

Response

data.leafnodeServiceCA (certificatePEM shortened in the example):

CertificateStatus is one of VALID, EXPIRING_SOON, EXPIRED_WARNING, EXPIRED_ERROR, MISSING.

Errors

GraphQL endpoints return 200 OK even on logical errors. Inspect the errors array in the response body:

{ "errors": [ { "message": "...", "path": ["..."], "extensions": { "code": "..." } } ] }

A non-200 HTTP response means DeviceHub itself is unreachable. See Dashboard > DeviceHub Status.

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

GraphQL Query

query LeafnodeServiceCA {
  leafnodeServiceCA { certificatePEM status daysUntilExpiry statusMessage affectedHubAccounts fingerprint subject }
}

Response

Status: 200 OK

{
    "data": {
        "leafnodeServiceCA": {
            "certificatePEM": "-----BEGIN CERTIFICATE-----\nMIIDzDCCArSgAwIBAgIRAJNuLHTaM9EiwHyErpLE7vkwDQYJKoZIhvcNAQELBQAw\n...\n-----END CERTIFICATE-----\n",
            "status": "VALID",
            "daysUntilExpiry": 3415,
            "statusMessage": "Valid",
            "affectedHubAccounts": 1,
            "fingerprint": "b763d44e74586b53c56e5b1cea49e8139f54d9e4a1d93f9b139e6ae3448b359c",
            "subject": "CN=LoopEdge Access Leafnode CA (litmus-edge-005056b9b678),O=Litmus Automation"
        }
    }
}

List Installed Hub CAs

POST {{edgeUrl}}/access/v2

List Installed Hub CAs

Lists the CA certificates of remote hubs installed on this device, which it uses to trust those hubs when it connects as a leaf.

Part of the Access service GraphQL API at /access/v2, which manages the device's NATS proxy and NATS leafnode links (this device as a leaf of a remote hub, as a hub for remote leafs, or both). For connecting a NATS client to the device, see the How-To: Authenticate a NATS / DataHub Client section.

Endpoint

POST {{edgeUrl}}/access/v2

Authentication

HTTP Basic Auth. Username is your API token, password is empty. The same token is valid across /devicehub/v2, /analytics/v2, /cc, /opcua, and the other LE services.

Query

query InstalledLeafnodeCAs {
  installedLeafnodeCAs { hubHostname status daysUntilExpiry statusMessage fingerprint }
}

No variables.

Response

data.installedLeafnodeCAs is a list (empty when none are installed):

CertificateStatus is one of VALID, EXPIRING_SOON, EXPIRED_WARNING, EXPIRED_ERROR, MISSING.

Errors

GraphQL endpoints return 200 OK even on logical errors. Inspect the errors array in the response body:

{ "errors": [ { "message": "...", "path": ["..."], "extensions": { "code": "..." } } ] }

A non-200 HTTP response means DeviceHub itself is unreachable. See Dashboard > DeviceHub Status.

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

GraphQL Query

query InstalledLeafnodeCAs {
  installedLeafnodeCAs { hubHostname status daysUntilExpiry statusMessage fingerprint }
}

Response

Status: 200 OK

{
    "data": {
        "installedLeafnodeCAs": []
    }
}

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

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

[
  {
    "id": "a1b2c3d4-a1b2-c3d4-a1b2-a1b2c3d4a1b2",
    "name": "testKey",
    "readOnly": false,
    "value": "abcdabcdabcdabcdabcdabcdabcdabcd"
  }
]

Errors

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

[
    {
        "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

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

{ "name": "testAPIKey" }

Errors

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

{
    "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

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

{ "value": "testAPIKey" }

Errors

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

{
    "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

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

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

{
    "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

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

{ "name": "renameTestAPIKey" }

Errors

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

{
    "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

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

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 OAuth2 Clients

GET {{edgeUrl}}/auth/v3/oauth/client

List OAuth2 Clients

Lists the OAuth2 client-credentials clients defined on the device. A client exchanges its ID and secret for a short-lived bearer token; see How-To: Use OAuth2 Authorization.

Endpoint

GET {{edgeUrl}}/auth/v3/oauth/client

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. One entry per client:

Errors

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

[
    {
        "clientName": "codex",
        "clientID": "0eb3360d-0f65-4a46-83ff-f0e48ec6bfd2",
        "clientSecret": "",
        "groups": [
            "Administrators"
        ],
        "tokenTTLMinutes": 5
    },
    {
        "clientName": "litmus-cli-cd303318c74a-1783639596",
        "clientID": "21571a9f-a2d1-4a5d-bed1-538544bc087a",
        "clientSecret": "",
        "groups": [
            "Administrators"
        ],
        "tokenTTLMinutes": 5
    },
    {
        "clientName": "litmus-cli-134e7f11cb31-1791501363",
        "clientID": "28b9db5f-0fb8-43a2-930f-70ae4f5d8573",
        "clientSecret": "",
        "groups": [
            "Administrators"
        ],
        "tokenTTLMinutes": 5
    },
    {
        "clientName": "PlantBrain2",
        "clientID": "2b83232b-35e2-4432-96f2-a8bef15bc63b",
        "clientSecret": "",
        "groups": [
            "Administrators"
        ],
        "tokenTTLMinutes": 5
    },
    {
        "clientName": "plugin2",
        "clientID": "311a17ec-1e2f-4963-a946-b1bfde01cbf9",
        "clientSecret": "",
        "groups": [
            "Administrators"
        ],
        "tokenTTLMinutes": 5
    },
    {
        "clientName": "litmus-sdk-cli-f7b0585688b6-1783632585",
        "clientID": "31a4bfdb-25c0-40b0-9d6f-c6cddb155fa4",
        "clientSecret": "",
        "groups": [
            "Administrators"
        ],
        "tokenTTLMinutes": 5
    },
    {
        "clientName": "PlantBrain",
        "clientID": "3b43b0be-025f-4ded-abac-0cbceada2a49",
        "clientSecret": "",
        "groups": [
            "Administrators"
        ],
        "tokenTTLMinutes": 5
    },
    {
        "clientName": "litmus-cli-a15717ee469f-1783646477",
        "clientID": "52d99fb2-2930-432e-a81e-ba9e123b799b",
        "clientSecret": "",
        "groups": [
            "Administrators"
        ],
        "tokenTTLMinutes": 5
    },
    {
        "clientName": "claw",
        "clientID": "52e84614-64a3-4e84-bb75-783c175ed2ce",
        "clientSecret": "",
        "groups": [
            "Administrators"
        ],
        "tokenTTLMinutes": 5
    },
    {
        "clientName": "sdk",
        "clientID": "52f32c4f-6b65-4b59-972e-16b4ece0dc43",
        "clientSecret": "",
        "groups": [
            "Administrators"
        ],
        "tokenTTLMinutes": 5
    },
    {
        "clientName": "litmus-cli-9361254c330c-1783645595",
        "clientID": "5926a9cc-0ea2-4132-9279-82fa199de816",
        "clientSecret": "",
        "groups": [
            "Administrators"
        ],
        "tokenTTLMinutes": 5
    },
    {
        "clientName": "ubuntuvm",
        "clientID": "61d16499-eadf-4377-941f-eb7d04e42c6f",
        "clientSecret": "",
        "groups": [
            "Administrators"
        ],
        "tokenTTLMinutes": 5
    },
    {
        "clientName": "litmus-cli-073c696c87cc-1784072348",
        "clientID": "68bc4f12-247f-43e8-8d38-dd9358e2948f",
        "clientSecret": "",
        "groups": [
            "Administrators"
        ],
        "tokenTTLMinutes": 5
    },
    {
        "clientName": "hello",
        "clientID": "6dd1d8ef-6d47-4d7e-b327-c0bcb2da03cb",
        "clientSecret": "",
        "groups": [
            "Administrators"
        ],
        "tokenTTLMinutes": 5
    },
    {
        "clientName": "litmussdk",
        "clientID": "6f288543-46b9-4dda-a55c-b43c886ee9e9",
        "clientSecret": "",
        "groups": [
            "Administrators"
        ],
        "tokenTTLMinutes": 5
    },
    {
        "clientName": "litmus-cli-0c0624539c52-1783978757",
        "clientID": "843c377f-1010-4b04-aaa5-ecf9e042e768",
        "clientSecret": "",
        "groups": [
            "Administrators"
        ],
        "tokenTTLMinutes": 5
    },
    {
        "clientName": "plugin",
        "clientID": "954eb555-8125-4311-8b00-df17d5aec2b0",
        "clientSecret": "",
        "groups": [
            "Administrators"
        ],
        "tokenTTLMinutes": 5
    },
    {
        "clientName": "parth2",
        "clientID": "9f01f081-14cd-459f-bf57-4a21529d597f",
        "clientSecret": "",
        "groups": [
            "Administrators"
        ],
        "tokenTTLMinutes": 5
    },
    {
        "clientName": "litmus-cli-a15717ee469f-1783646512",
        "clientID": "c8b2d48b-b0fd-4a33-9ae1-0ccf5051b71d",
        "clientSecret": "",
        "groups": [
            "Administrators"
        ],
        "tokenTTLMinutes": 5
    }
]

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

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

{
  "name": "api_access_account",
  "enabled": true
}

Response

{
  "id": "31391416-4162-4df5-855e-9b2e0e09536b",
  "name": "api_access_account",
  "enabled": true,
  "apikey": "2936b9f4-2928-494c-8eb4-cdc8bd93b770"
}

Errors

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

{
    "name": "api_access_account",
    "enabled": true
}

Response

Status: 200 OK

{
    "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

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

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

[
    {
        "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

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

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

{
    "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

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

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

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

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

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

{
  "id": "fcf5e5e4-0951-44c1-987a-a021495115b4",
  "name": "accessAccount",
  "enabled": true,
  "apikey": "3fae4dcf-9852-4a15-adc8-a07f703af9f6"
}

Errors

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

{
    "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

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

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

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

{ "read": [">"], "write": null }

Errors

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

{
    "read": [
        ">"
    ],
    "write": null
}

Add Read Topic

PUT {{edgeUrl}}/access/accounts/access/{{access_account_api_key}}?accessType=read&topics={{access_read_topic}}

Add Read Topic

Requires: the account's API key, not its id. The key is the apikey field of the Create Access Account response (or of Get Access Account API Key). Using the account id in the path returns 404.

Grants the account read access to one NATS topic pattern.

Endpoint

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

Errors

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

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

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

Requires: the account's API key, not its id. The key is the apikey field of the Create Access Account response (or of Get Access Account API Key). Using the account id in the path returns 404.

Grants the account write access to one NATS topic pattern.

Endpoint

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

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

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

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

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:

Errors

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

[
    {
        "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

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:

{
  "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

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

{
    "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

{
    "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

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

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

{
    "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

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

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

{
    "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

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

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

{
    "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

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

[
  {
    "dn": "CN=loopedge-observer,CN=Users,DC=l4d,DC=win",
    "id": "...",
    "name": "...",
    "role": "Viewer"
  }
]

Errors

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

[
    {
        "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

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

{ "roleName": "administrator" }

Errors

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

{
    "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

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

{ "status": "OK" }

Errors

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

{
    "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

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

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 Authentication Providers

GET {{edgeUrl}}/auth/v2/login

List Authentication Providers

The authentication providers a client can log in against, as the login screen renders them.

Endpoint

GET {{edgeUrl}}/auth/v2/login

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. One id and name per provider. The all-zero UUID 00000000-0000-0000-0000-000000000000 is local authentication and carries an empty name; every other entry is a configured LDAP, AD or OIDC provider.

Unlike List Auth Providers, this returns no provider configuration, so it is the safe call for building a login picker.

The POST on the same path is the browser login and is not used by token-based clients, which present the API token directly.

Errors

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

[
    {
        "id": "00000000-0000-0000-0000-000000000000",
        "name": ""
    },
    {
        "id": "b33adbc4-f8ce-4fec-85ed-29c4bb3c5fa0",
        "name": "ad"
    }
]

List Directory Groups

GET {{edgeUrl}}/auth/v3/providers/{{auth_provider_id}}/groups

List Directory Groups

Lists the groups found in an LDAP / AD provider's directory, for mapping them to internal user groups. The web UI calls it when you open a provider's group mapping. Unlike List Provider User Groups (/auth/v2), the device queries the directory live on every call.

Endpoint

GET {{edgeUrl}}/auth/v3/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.

Path parameters

Response

200 OK -- application/json, the directory's groups. Because the directory is contacted on each call, a provider the device cannot reach or whose certificate it does not trust returns 500, for example {"error":{"Msg":"failed to connect: LDAP Result Code 200 \"Network Error\": tls: failed to verify certificate: x509: certificate signed by unknown authority","MsgCode":""}}. Run Test Configuration first if this happens. An unknown provider ID returns 404 with {"error":{"Msg":"provider not found","MsgCode":""}}.

Errors

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.

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

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

[
  { "alias": "none",               "name": "None" },
  { "alias": "warning",            "name": "Warning" },
  { "alias": "stopDataCollection", "name": "Stop data collection" }
]

Errors

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

[
    {
        "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

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

[
  { "alias": "stopDataCollection", "name": "Stop data collection" },
  { "alias": "shutdown",           "name": "Shutdown" }
]

Errors

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

[
    {
        "alias": "stopDataCollection",
        "name": "Stop data collection"
    },
    {
        "alias": "shutdown",
        "name": "Shutdown"
    }
]

Show Current or Default Password Policy

GET {{edgeUrl}}/auth/v2/password/policy/{{default}}

Show Current or Default Password Policy

Returns the password policy. The last path segment is a boolean: true returns the factory default, false returns the current (possibly customized) policy.

Endpoint

GET {{edgeUrl}}/auth/v2/password/policy/{{default}}

Authentication

HTTP Basic Auth. Username is your API token, password is empty. Tokens are managed under System > Access Control > Tokens.

Path parameters

Response

{
  "genCharacterLength": 12,
  "maxCharacterLength": 256,
  "minCharacterLength": 8,
  "minDigits": 1,
  "minLowercaseChars": 1,
  "minSpecialChars": 1,
  "minUppercaseChars": 1,
  "specialChars": "~!@#$%^&*()_-{}[]|;:,.<>?/"
}

Errors

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

{
    "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

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

{ "password": "123" }

Response

200 OK -- application/json. Reports isSufficient plus a per-requirement breakdown.

{
  "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

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

{
    "password": "123"
}

Response

Status: 200 OK

{
    "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

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

{
  "currentPassword": "************",
  "newPassword":     "************"
}

Errors

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

{
    "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

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

{
  "genCharacterLength": 12,
  "maxCharacterLength": 20,
  "minCharacterLength": 8,
  "minDigits": 1,
  "minLowercaseChars": 1,
  "minSpecialChars": 1,
  "minUppercaseChars": 1,
  "specialChars": "!\"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~"
}

Errors

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

{
    "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

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

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

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

{
  "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"]
}

Errors

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

{
    "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

{
    "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

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

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

{
    "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

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

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

{
    "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

{
    "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

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

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

[
    {
        "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

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

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

Validate OIDC Discovery URL

POST {{edgeUrl}}/auth/v3/oidc/discover

Validate OIDC Discovery URL

Fetches an OpenID Connect discovery document from the device and returns the issuer it declares. The web UI calls it when you enter the well-known URL in the OIDC provider form, and only enables the Client ID and Client Secret fields once it succeeds. Nothing is saved.

Endpoint

POST {{edgeUrl}}/auth/v3/oidc/discover

Authentication

HTTP Basic Auth. Username is your API token, password is empty. Tokens are managed under System > Access Control > Tokens.

Request body

{ "url": "https://accounts.google.com/.well-known/openid-configuration" }

Response

200 OK -- application/json.

The request is made from the device, so the device needs network access to the provider. An unreachable host returns 500 with {"error":{"Msg":"failed to send dicovery request: ...","MsgCode":""}}. A missing url returns a missing_field error (500 on 4.0.x, 400 on 4.3.x).

Errors

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

{
    "url": "{{oidc_well_known_url}}"
}

Response

Status: 200 OK

{
    "registration": "",
    "issuer": "https://accounts.google.com",
    "warnIssuerMismatch": false
}