# LitmusEdge 4.0.x API Documentation/System/Activation - LE, LEM, LUNS API Docs

## List Installed License/s

**GET** `{{edgeUrl}}/lic/v2/licenses`

# List Installed License/s

Returns every license currently installed on the device with its status, expiry, and trial/core flags.

## Endpoint

```http
GET {{edgeUrl}}/lic/v2/licenses
```
## 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 license objects.

| Field          | Type    | Description                                                       |
|----------------|---------|-------------------------------------------------------------------|
| `name`         | string  | License product key (e.g. `litmusedge-scale-nl`).                  |
| `key`          | string  | Activation key (masked once installed).                            |
| `status`       | string  | `OK`, `Expired`, `Invalid`, ...                                    |
| `expiryDate`   | string  | Expiry timestamp (UTC).                                           |
| `expiryDays`   | integer | Days remaining until expiry.                                       |
| `isTrial`      | boolean | `true` for evaluation licenses.                                    |
| `isCore`       | boolean | `true` for the device's primary license.                           |

```json
[
  {
    "name": "litmusedge-scale-nl",
    "key": "xxxx-xxxx-xxxx-xxxx",
    "status": "OK",
    "expiryDate": "2024-04-25 00:00:00 +0000 UTC",
    "expiryDays": 270,
    "isTrial": false,
    "isCore": true
  }
]
```

## Errors

| HTTP status         | When it happens                                                                |
|---------------------|--------------------------------------------------------------------------------|
| `400 Bad Request`   | Missing or malformed query/body parameter.                                     |
| `401 Unauthorized`  | Missing or invalid credentials.                                                |
| `403 Forbidden`     | Token lacks permission for this operation.                                     |
| `404 Not Found`     | Target entity does not exist.                                                  |
| `5xx`               | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. |

> **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly.


### Response

**Status**: 200 OK

```json
[
    {
        "name": "litmusedge-scale-nl",
        "key": "xxxx-xxxx-xxxx-xxxx",
        "status": "OK",
        "expiryDate": "2024-04-25 00:00:00 +0000 UTC",
        "expiryDays": 270,
        "isTrial": false,
        "isCore": true
    }
]
```

---

## Online License Activation

**POST** `{{edgeUrl}}/lic/v2/activation/online`

# Online License Activation

Activates the device against the LE licensing portal using an activation key. Requires outbound HTTPS access from the device to the licensing service.

For air-gapped deployments, use the `Generate Offline License Request` flow instead.

## Endpoint

```http
POST {{edgeUrl}}/lic/v2/activation/online
```
## Authentication

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

## Request body

```json
{
  "key": "{{online_license_activation}}"
}
```

| Field   | Type   | Required | Description                                                                |
|---------|--------|----------|----------------------------------------------------------------------------|
| `key`   | string | Yes      | Activation key in the format `XXXX-XXXX-XXXX-XXXX`.                        |

## Response

`200 OK` on success. The installed license appears in `List Installed License/s`.

## Errors

| HTTP status         | When it happens                                                                |
|---------------------|--------------------------------------------------------------------------------|
| `400 Bad Request`   | Missing or malformed query/body parameter.                                     |
| `401 Unauthorized`  | Missing or invalid credentials.                                                |
| `403 Forbidden`     | Token lacks permission for this operation.                                     |
| `404 Not Found`     | Target entity does not exist.                                                  |
| `5xx`               | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. |

> **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly.


### Request Body

```json
{
    "key": "{{online_license_activation}}"
}
```

### Response

**Status**: 204 No Content

---

## Generate Offline License Request

**GET** `{{edgeUrl}}/lic/v2/activation/offline?key={{offline_license_activation}}`

# Generate Offline License Request

Generates an **offline license request blob** that can be uploaded to the LE licensing portal (in a separate online session) to produce the matching offline activation key. Use for devices with no outbound internet access.

## Endpoint

```http
GET {{edgeUrl}}/lic/v2/activation/offline?key={{offline_license_activation}}
```
## Authentication

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

## Query parameters

| Parameter | Type   | Required | Description                                  |
|-----------|--------|----------|----------------------------------------------|
| `key`     | string | Yes      | Activation key issued by the licensing portal. |

## Response

`200 OK` -- `application/json`

| Field      | Type   | Description                                                                |
|------------|--------|----------------------------------------------------------------------------|
| `request`  | string | Opaque base64 blob. Paste verbatim into the licensing portal's "offline activation" form. |

```json
{ "request": "{your offline license activation request will appear here}" }
```

After receiving the offline license file from the portal, install it via a separate POST flow exposed by the LE UI.

## Errors

| HTTP status         | When it happens                                                                |
|---------------------|--------------------------------------------------------------------------------|
| `400 Bad Request`   | Missing or malformed query/body parameter.                                     |
| `401 Unauthorized`  | Missing or invalid credentials.                                                |
| `403 Forbidden`     | Token lacks permission for this operation.                                     |
| `404 Not Found`     | Target entity does not exist.                                                  |
| `5xx`               | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. |

> **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly.


### Response

**Status**: 200 OK

```json
{
    "request": "{your offline license activation request will appear here}"
}
```

---

## Delete a License

**DELETE** `{{edgeUrl}}/lic/v2/licenses/{key}`

# Delete a License

Removes a license by its activation key. Features unlocked solely by the deleted license stop working immediately. The core/primary license should not be removed except as part of a re-activation flow.

## Endpoint

```http
DELETE {{edgeUrl}}/lic/v2/licenses/{key}
```
## Authentication

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

## Path parameters

| Location | Name    | Required | Description                                  |
|----------|---------|----------|----------------------------------------------|
| Path     | `{key}` | Yes      | Activation key (from `List Installed License/s > key`). |

## Response

`200 OK` on success.

## Errors

| HTTP status         | When it happens                                                                |
|---------------------|--------------------------------------------------------------------------------|
| `400 Bad Request`   | Missing or malformed query/body parameter.                                     |
| `401 Unauthorized`  | Missing or invalid credentials.                                                |
| `403 Forbidden`     | Token lacks permission for this operation.                                     |
| `404 Not Found`     | Target entity does not exist.                                                  |
| `5xx`               | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. |

> **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly.


---

## List Features Currently in Use

**GET** `{{edgeUrl}}/lic/v2/features`

# List Features Currently in Use

Returns each licensed feature (`marketplace`, `analytics`, `devices`, `backup`, ...) with its current count and expiry. `count: -1` means the feature is unmetered.

## Endpoint

```http
GET {{edgeUrl}}/lic/v2/features
```
## Authentication

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

## Response

`200 OK` -- `application/json`

| Field     | Type    | Description                                                                |
|-----------|---------|----------------------------------------------------------------------------|
| `name`    | string  | Feature key (`marketplace`, `analytics`, `devices`, `tags`, `backup`, ...). |
| `desc`    | string  | Human-readable description.                                                |
| `count`   | integer | Current usage count. `-1` for unmetered features.                          |
| `expires` | string  | Expiry timestamp.                                                          |
| `limited` | boolean | `true` if there is a hard limit beyond the count.                          |

```json
[
  { "name": "marketplace", "desc": "Marketplace", "count": -1, "expires": "2024-04-25T00:00:00Z", "limited": false },
  { "name": "analytics",   "desc": "Analytics",   "count": -1, "expires": "2024-04-25T00:00:00Z", "limited": false }
]
```

## Errors

| HTTP status         | When it happens                                                                |
|---------------------|--------------------------------------------------------------------------------|
| `400 Bad Request`   | Missing or malformed query/body parameter.                                     |
| `401 Unauthorized`  | Missing or invalid credentials.                                                |
| `403 Forbidden`     | Token lacks permission for this operation.                                     |
| `404 Not Found`     | Target entity does not exist.                                                  |
| `5xx`               | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. |

> **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly.


### Response

**Status**: 200 OK

```json
[
    {
        "name": "marketplace",
        "desc": "Marketplace",
        "count": -1,
        "expires": "2024-04-25T00:00:00Z",
        "limited": false
    },
    {
        "name": "analytics",
        "desc": "Analytics",
        "count": -1,
        "expires": "2024-04-25T00:00:00Z",
        "limited": false
    },
    {
        "name": "devices",
        "desc": "Devices",
        "count": -1,
        "expires": "2024-04-25T00:00:00Z",
        "limited": false
    },
    {
        "name": "backup",
        "desc": "Backup",
        "count": -1,
        "expires": "2024-04-25T00:00:00Z",
        "limited": false
    },
    {
        "name": "core",
        "desc": "Core",
        "count": -1,
        "expires": "2024-04-25T00:00:00Z",
        "limited": false
    },
    {
        "name": "updates",
        "desc": "Software updates",
        "count": -1,
        "expires": "2024-04-25T00:00:00Z",
        "limited": false
    },
    {
        "name": "tags",
        "desc": "Tags",
        "count": -1,
        "expires": "2024-04-25T00:00:00Z",
        "limited": true
    },
    {
        "name": "dt",
        "desc": "Digtial twins",
        "count": -1,
        "expires": "2024-04-25T00:00:00Z",
        "limited": false
    },
    {
        "name": "opcua",
        "desc": "OPCUA",
        "count": -1,
        "expires": "2024-04-25T00:00:00Z",
        "limited": false
    }
]
```

---

## Get Product Info

**GET** `{{edgeUrl}}/lic/v2/info`

# Get Product Info

Returns the product identity bundle: product name, version, product ID, and the license product ID. Use this when filing support tickets to confirm which SKU is deployed.

## Endpoint

```http
GET {{edgeUrl}}/lic/v2/info
```
## Authentication

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

## Response

`200 OK` -- `application/json`

| Field               | Type   | Description                                                       |
|---------------------|--------|-------------------------------------------------------------------|
| `productName`       | string | Product name (e.g. `Litmus Edge`).                                |
| `productVersion`    | string | Product version.                                                  |
| `productId`         | string | SKU identifier (e.g. `litmusedge-std`).                            |
| `productLicenseId`  | string | License-system identifier.                                         |

```json
{
  "productName": "Litmus Edge",
  "productVersion": "3.5.6",
  "productId": "litmusedge-std",
  "productLicenseId": "litmusedge"
}
```

## Errors

| HTTP status         | When it happens                                                                |
|---------------------|--------------------------------------------------------------------------------|
| `400 Bad Request`   | Missing or malformed query/body parameter.                                     |
| `401 Unauthorized`  | Missing or invalid credentials.                                                |
| `403 Forbidden`     | Token lacks permission for this operation.                                     |
| `404 Not Found`     | Target entity does not exist.                                                  |
| `5xx`               | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. |

> **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly.


### Response

**Status**: 200 OK

```json
{
    "productName": "Litmus Edge",
    "productVersion": "3.5.6",
    "productId": "litmusedge-std",
    "productLicenseId": "litmusedge"
}
```

---

## License Server Configured Limits

**GET** `{{edgeUrl}}/lic/v2/limits`

# License Server Configured Limits

Returns the effective / hard / user limits per feature, plus reservation values when the license server enforces reserved quotas. Used to detect when feature usage is approaching its cap.

## Endpoint

```http
GET {{edgeUrl}}/lic/v2/limits
```
## 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 `{feature, limits, reservations}` objects.

| Field                          | Type    | Description                                                            |
|--------------------------------|---------|------------------------------------------------------------------------|
| `feature`                      | string  | Feature key.                                                           |
| `limits.effective`             | integer | Current usable limit (after applying any administrative overrides).    |
| `limits.hard`                  | integer | License-imposed ceiling that cannot be exceeded.                       |
| `limits.user`                  | integer | Operator-set soft limit (may be lower than the hard limit).            |
| `reservations.*`               | integer | Same three counters for any reserved-quota allocations.                |

```json
[
  {
    "feature": "tags",
    "limits": { "effective": 500, "hard": 500, "user": 500 },
    "reservations": { "effective": 500, "hard": 500, "user": 500 }
  }
]
```

## Errors

| HTTP status         | When it happens                                                                |
|---------------------|--------------------------------------------------------------------------------|
| `400 Bad Request`   | Missing or malformed query/body parameter.                                     |
| `401 Unauthorized`  | Missing or invalid credentials.                                                |
| `403 Forbidden`     | Token lacks permission for this operation.                                     |
| `404 Not Found`     | Target entity does not exist.                                                  |
| `5xx`               | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. |

> **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly.


### Response

**Status**: 200 OK

```Text
[
    {
        "feature": "tags",
        "limits": {
            "effective": 500,
            "hard": 500,
            "user": 500
        },
        "reservations": {
            "effective": 500,
            "hard": 500,
            "user": 500
        }
    },
    {
        "feature": "tags",
        "limits": {
            "effective": 500,
            "hard": 500,
            "user": 500
        },
        "reservations": {
            "effective": 500,
            "hard": 500,
            "user": 500
        }
    },
    {
        "feature": "tags",
        "limits": {
            "effective": 500,
            "hard": 500,
            "user": 500
        },
        "reservations": {
            "effective": 500,
            "hard": 500,
            "user": 500
        }
    }
]
```

---

## Show Registration Status

**GET** `{{edgeUrl}}/dm/cloud`

# Show Registration Status

Returns whether the device is currently registered with **LE Manager** (the cloud / on-prem management server) and, if so, which company, project, and model it is enrolled under. `activatedAt` returns the sentinel `0001-01-01T00:00:00Z` when the device is not registered.

## Endpoint

```http
GET {{edgeUrl}}/dm/cloud
```
## Authentication

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

## Response

`200 OK` -- `application/json`

| Field           | Type   | Description                                                                |
|-----------------|--------|----------------------------------------------------------------------------|
| `activatedAt`   | string | Registration timestamp (UTC). Sentinel `0001-01-01T00:00:00Z` if not registered. |
| `companyID` / `companyName` | string | LE Manager organization identifiers.                            |
| `projectID` / `projectName` | string | Project the device belongs to.                                  |
| `modelID` / `modelName`     | string | Device model classification on LE Manager.                       |
| `deviceID`      | string | LE Manager-issued device UUID.                                              |
| `status`        | string | Overall status (`OK`, ...).                                                |
| `statusCode`    | string | Machine-readable status code; empty on healthy registration.               |

```json
{
  "activatedAt": "0001-01-01T00:00:00Z",
  "companyID": "",
  "companyName": "solutions",
  "deviceID": "1a5wiavluwxuhwai5leb1v0hc",
  "modelID": "6vuut3v2qm36fv7smna42ckj3",
  "modelName": "LoopEdge",
  "projectID": "462j1mq70mph31wa100t1yuxa",
  "projectName": "apiProject",
  "status": "OK",
  "statusCode": ""
}
```

## Errors

| HTTP status         | When it happens                                                                |
|---------------------|--------------------------------------------------------------------------------|
| `400 Bad Request`   | Missing or malformed query/body parameter.                                     |
| `401 Unauthorized`  | Missing or invalid credentials.                                                |
| `403 Forbidden`     | Token lacks permission for this operation.                                     |
| `404 Not Found`     | Target entity does not exist.                                                  |
| `5xx`               | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. |

> **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly.


### Response

**Status**: 200 OK

```json
{
    "activatedAt": "0001-01-01T00:00:00Z",
    "companyID": "",
    "companyName": "solutions",
    "deviceID": "1a5wiavluwxuhwai5leb1v0hc",
    "modelID": "6vuut3v2qm36fv7smna42ckj3",
    "modelName": "LoopEdge",
    "projectID": "462j1mq70mph31wa100t1yuxa",
    "projectName": "apiProject",
    "status": "OK",
    "statusCode": ""
}
```

---

## Register With Cloud

**POST** `{{edgeUrl}}/dm/cloud`

# Register With Cloud

Registers the device with LE Manager using a registration **code** the operator obtained from the LE Manager UI. After this call returns successfully, `Show Registration Status > activatedAt` is set.

## Endpoint

```http
POST {{edgeUrl}}/dm/cloud
```
## Authentication

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

## Request body

```json
{
  "code": "H3LIB-QTM6B-7PVNA-4KSAZ-B04QL"
}
```

| Field   | Type   | Required | Description                                                       |
|---------|--------|----------|-------------------------------------------------------------------|
| `code`  | string | Yes      | Hyphen-separated registration code from LE Manager.               |

## Response

`200 OK` on success.

## Errors

| HTTP status         | When it happens                                                                |
|---------------------|--------------------------------------------------------------------------------|
| `400 Bad Request`   | Missing or malformed query/body parameter.                                     |
| `401 Unauthorized`  | Missing or invalid credentials.                                                |
| `403 Forbidden`     | Token lacks permission for this operation.                                     |
| `404 Not Found`     | Target entity does not exist.                                                  |
| `5xx`               | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. |

> **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly.


### Request Body

```json
{
    "code": "H3LIB-QTM6B-7PVNA-4KSAZ-B04QL"
}
```

---

## De-Register with Cloud

**DELETE** `{{edgeUrl}}/dm/cloud`

# De-Register with Cloud

Removes the device's LE Manager registration. After this call the device operates standalone; LE Manager will mark the device offline on its next reconciliation cycle.

## Endpoint

```http
DELETE {{edgeUrl}}/dm/cloud
```
## Authentication

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

## Response

`200 OK` on success.

## Errors

| HTTP status         | When it happens                                                                |
|---------------------|--------------------------------------------------------------------------------|
| `400 Bad Request`   | Missing or malformed query/body parameter.                                     |
| `401 Unauthorized`  | Missing or invalid credentials.                                                |
| `403 Forbidden`     | Token lacks permission for this operation.                                     |
| `404 Not Found`     | Target entity does not exist.                                                  |
| `5xx`               | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. |

> **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly.


---

## Show Backup Interval

**GET** `{{edgeUrl}}/dm/cloud/backupInterval`

# Show Backup Interval

Returns the cadence (in **minutes**) at which the device pushes its backup to LE Manager.

## Endpoint

```http
GET {{edgeUrl}}/dm/cloud/backupInterval
```
## 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`

```json
{ "interval": 5 }
```

| Field        | Type    | Description                                  |
|--------------|---------|----------------------------------------------|
| `interval`   | integer | Backup interval in minutes.                  |

## Errors

| HTTP status         | When it happens                                                                |
|---------------------|--------------------------------------------------------------------------------|
| `400 Bad Request`   | Missing or malformed query/body parameter.                                     |
| `401 Unauthorized`  | Missing or invalid credentials.                                                |
| `403 Forbidden`     | Token lacks permission for this operation.                                     |
| `404 Not Found`     | Target entity does not exist.                                                  |
| `5xx`               | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. |

> **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly.


### Response

**Status**: 200 OK

```json
{
    "interval": 5
}
```

---

## Set Backup Interval

**PUT** `{{edgeUrl}}/dm/cloud/backupInterval`

# Set Backup Interval

Updates the cadence (in **minutes**) at which the device pushes its backup to LE Manager. Set to `0` to disable scheduled backups.

## Endpoint

```http
PUT {{edgeUrl}}/dm/cloud/backupInterval
```
## Authentication

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

## Request body

```json
{ "interval": 5 }
```

| Field        | Type    | Required | Description                                  |
|--------------|---------|----------|----------------------------------------------|
| `interval`   | integer | Yes      | Backup interval in minutes (`0` disables).   |

## Response

`200 OK` on success.

## Errors

| HTTP status         | When it happens                                                                |
|---------------------|--------------------------------------------------------------------------------|
| `400 Bad Request`   | Missing or malformed query/body parameter.                                     |
| `401 Unauthorized`  | Missing or invalid credentials.                                                |
| `403 Forbidden`     | Token lacks permission for this operation.                                     |
| `404 Not Found`     | Target entity does not exist.                                                  |
| `5xx`               | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. |

> **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly.


### Request Body

```json
{
    "interval": 5
}
```

### Response

**Status**: 204 No Content

---

## Show Cloud URL

**GET** `{{edgeUrl}}/dm/cloud/url`

# Show Cloud URL

Returns the LE Manager URL the device is configured to talk to. Use to verify before / after `Set Cloud URL`.

## Endpoint

```http
GET {{edgeUrl}}/dm/cloud/url
```
## 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`

```json
{ "url": "https://10.17.3.103" }
```

## Errors

| HTTP status         | When it happens                                                                |
|---------------------|--------------------------------------------------------------------------------|
| `400 Bad Request`   | Missing or malformed query/body parameter.                                     |
| `401 Unauthorized`  | Missing or invalid credentials.                                                |
| `403 Forbidden`     | Token lacks permission for this operation.                                     |
| `404 Not Found`     | Target entity does not exist.                                                  |
| `5xx`               | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. |

> **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly.


### Response

**Status**: 200 OK

```json
{
    "url": "https://10.17.3.103"
}
```

---

## Set Cloud URL

**POST** `{{edgeUrl}}/dm/cloud/url`

# Set Cloud URL

Proposes a new LE Manager URL. The change is **two-step**: this call returns transaction metadata + the remote server's certificate; the operator then either confirms (`Thrust Remote Server and Complete Cloud URL Transaction`) or declines (`Decline Set URL Request`).

This trust-on-first-use flow prevents an attacker who can briefly DNS- hijack the device from silently re-pointing it to a malicious LE Manager.

## Endpoint

```http
POST {{edgeUrl}}/dm/cloud/url
```
## Authentication

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

## Request body

```json
{ "url": "https://10.17.3.103" }
```

## Response

`200 OK` -- `application/json`

| Field                  | Type   | Description                                                                |
|------------------------|--------|----------------------------------------------------------------------------|
| `certIssuer`           | string | Issuer DN of the remote server's TLS certificate.                          |
| `certSubject`          | string | Subject DN.                                                                |
| `certNotBefore` / `certNotAfter` | string | Certificate validity window.                                     |
| `certValidationErrors` | array  | Any TLS validation issues (`null` for a clean cert).                       |
| `tx`                   | string | Transaction UUID. Pass to `Thrust...` or `Decline Set URL Request`.        |

```json
{
  "certIssuer": "CN=Litmus Edge Manager CA 23072022027",
  "certNotAfter": "2043-07-15 20:31:16 +0000 UTC",
  "certNotBefore": "2023-07-21 20:30:46 +0000 UTC",
  "certSubject": "CN=10.17.3.103",
  "certValidationErrors": null,
  "tx": "57051cea-94da-44b9-812a-fa8c746718aa"
}
```

## Errors

| HTTP status         | When it happens                                                                |
|---------------------|--------------------------------------------------------------------------------|
| `400 Bad Request`   | Missing or malformed query/body parameter.                                     |
| `401 Unauthorized`  | Missing or invalid credentials.                                                |
| `403 Forbidden`     | Token lacks permission for this operation.                                     |
| `404 Not Found`     | Target entity does not exist.                                                  |
| `5xx`               | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. |

> **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly.


### Request Body

```json
{
    "url": "https://10.17.3.103"
}
```

### Response

**Status**: 200 OK

```json
{
    "certIssuer": "CN=Litmus Edge Manager CA 23072022027",
    "certNotAfter": "2043-07-15 20:31:16 +0000 UTC",
    "certNotBefore": "2023-07-21 20:30:46 +0000 UTC",
    "certSubject": "CN=10.17.3.103",
    "certValidationErrors": null,
    "tx": "57051cea-94da-44b9-812a-fa8c746718aa"
}
```

---

## Reset Cloud URL to Default

**PUT** `{{edgeUrl}}/dm/cloud/url/resetToDefault`

# Reset Cloud URL to Default

Resets the LE Manager URL to the factory default. Useful to recover from a misconfigured override.

## Endpoint

```http
PUT {{edgeUrl}}/dm/cloud/url/resetToDefault
```
## Authentication

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

## Response

`200 OK` on success.

## Errors

| HTTP status         | When it happens                                                                |
|---------------------|--------------------------------------------------------------------------------|
| `400 Bad Request`   | Missing or malformed query/body parameter.                                     |
| `401 Unauthorized`  | Missing or invalid credentials.                                                |
| `403 Forbidden`     | Token lacks permission for this operation.                                     |
| `404 Not Found`     | Target entity does not exist.                                                  |
| `5xx`               | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. |

> **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly.


---

## Thrust Remote Server and Complete Cloud URL Transaction

**PUT** `{{edgeUrl}}/dm/cloud/url/{tx}/confirm`

# Trust Remote Server and Complete Cloud URL Transaction

Confirms a pending `Set Cloud URL` transaction. The device records the remote server's certificate fingerprint as trusted, then switches to the new URL.

(The Postman item's spelling -- "Thrust" -- is a typo; the underlying operation is "Trust".)

## Endpoint

```http
PUT {{edgeUrl}}/dm/cloud/url/{tx}/confirm
```
## Authentication

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

## Path parameters

| Location | Name    | Required | Description                                              |
|----------|---------|----------|----------------------------------------------------------|
| Path     | `{tx}`  | Yes      | Transaction UUID returned by `Set Cloud URL`.            |

## Response

`200 OK` on success.

## Errors

| HTTP status         | When it happens                                                                |
|---------------------|--------------------------------------------------------------------------------|
| `400 Bad Request`   | Missing or malformed query/body parameter.                                     |
| `401 Unauthorized`  | Missing or invalid credentials.                                                |
| `403 Forbidden`     | Token lacks permission for this operation.                                     |
| `404 Not Found`     | Target entity does not exist.                                                  |
| `5xx`               | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. |

> **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly.


---

## Decline Set URL Request

**DELETE** `{{edgeUrl}}/dm/cloud/url/{tx}/decline`

# Decline Set URL Request

Cancels a pending `Set Cloud URL` transaction. The previously configured URL is retained.

## Endpoint

```http
DELETE {{edgeUrl}}/dm/cloud/url/{tx}/decline
```
## Authentication

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

## Path parameters

| Location | Name    | Required | Description                                              |
|----------|---------|----------|----------------------------------------------------------|
| Path     | `{tx}`  | Yes      | Transaction UUID returned by `Set Cloud URL`.            |

## Response

`200 OK` on success.

## Errors

| HTTP status         | When it happens                                                                |
|---------------------|--------------------------------------------------------------------------------|
| `400 Bad Request`   | Missing or malformed query/body parameter.                                     |
| `401 Unauthorized`  | Missing or invalid credentials.                                                |
| `403 Forbidden`     | Token lacks permission for this operation.                                     |
| `404 Not Found`     | Target entity does not exist.                                                  |
| `5xx`               | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. |

> **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly.


---