# Litmus Edge Manager 3.0.x - Edge Lifecycle: OAuth Clients

## List Device OAuth Clients

**GET** `{{LEM_URL}}/api/v1/device/{{deviceID}}/oauth-clients`

> **New in 3.0.**

# List Device OAuth Clients

Lists the OAuth clients defined on an edge device. Secrets are never returned.
## Endpoint

```http
GET {{LEM_URL}}/api/v1/device/{{deviceID}}/oauth-clients
```
## Authentication

API key in a request header (case sensitive). The value is the LEM admin API token.

| URL prefix | Auth header |
|---|---|
| `{{LEM_URL}}/api/v1/...` (main fleet API) | `X-AuthToken: <token>` |
| `{{LEM_adminURL}}/admin/v1/...` (admin console, port 8446) | `X-AuthToken: <token>` |
| `{{LEM_URL}}/mpcs/...` (Marketplace Catalog) | `Authorization: <token>` (3.0.x also accepts `X-AuthToken`) |
## Parameters

| Parameter | In | Notes |
|---|---|---|
| `deviceId` | path | **Required.** The edge device. |

## Response

`200 OK`. An array of clients: `clientId`, `clientName`, the granted device groups, `tokenTtlMinutes` and `expiryTime` (epoch ms, absent when the client never expires). A device with no clients answers `[]`.

```json
[]
```
These are OAuth clients on the **edge device** (LitmusEdge), managed through LEM: LEM relays each call to the device, so the device must be online and run a LitmusEdge version that supports OAuth client management. A client gets an access token from the device's own token endpoint with the client-credentials grant and uses it against that device's APIs.

| Device state | Answer |
|---|---|
| Online, supported | `200` |
| Offline | `503`, `Device '<id>' is offline; OAuth clients can only be managed while the device is online` |
| Version not supported, or not detected yet | `501`, `Device '<id>' does not support OAuth client management` |

## 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
[]
```

---

## Create Device OAuth Client

**POST** `{{LEM_URL}}/api/v1/device/{{deviceID}}/oauth-clients`

> **New in 3.0.**

# Create Device OAuth Client

Creates an OAuth client on an edge device. The client secret is returned **once, in this response only**; store it immediately. Use `Regenerate Device OAuth Client Secret` if it is lost.
## Endpoint

```http
POST {{LEM_URL}}/api/v1/device/{{deviceID}}/oauth-clients
```
## Authentication

API key in a request header (case sensitive). The value is the LEM admin API token.

| URL prefix | Auth header |
|---|---|
| `{{LEM_URL}}/api/v1/...` (main fleet API) | `X-AuthToken: <token>` |
| `{{LEM_adminURL}}/admin/v1/...` (admin console, port 8446) | `X-AuthToken: <token>` |
| `{{LEM_URL}}/mpcs/...` (Marketplace Catalog) | `Authorization: <token>` (3.0.x also accepts `X-AuthToken`) |
## Parameters

| Parameter | In | Notes |
|---|---|---|
| `deviceId` | path | **Required.** The edge device. |

## Request body

| Field | Type | Notes |
|---|---|---|
| `clientName` | string | Display name. |
| `groupIds` | string[] | Device user groups the client is granted. The LEM UI requires at least one. |
| `tokenTtlMinutes` | integer | Access token lifetime, 1 to 30 minutes. The UI defaults to 5. |
| `expiryDate` | integer | Client expiry, Unix epoch milliseconds. Omit or `null` for a client that never expires. |

```json
{
  "clientName": "historian-reader",
  "groupIds": ["<device group id>"],
  "tokenTtlMinutes": 5,
  "expiryDate": null
}
```

## Response

`200 OK`. The new client with `clientId`, `clientSecret` and the device's `tokenEndpoint` (where the client requests tokens). These are OAuth clients on the **edge device** (LitmusEdge), managed through LEM: LEM relays each call to the device, so the device must be online and run a LitmusEdge version that supports OAuth client management. A client gets an access token from the device's own token endpoint with the client-credentials grant and uses it against that device's APIs.

| Device state | Answer |
|---|---|
| Online, supported | `200` |
| Offline | `503`, `Device '<id>' is offline; OAuth clients can only be managed while the device is online` |
| Version not supported, or not detected yet | `501`, `Device '<id>' does not support OAuth client management` |

Not exercised against a live device by these docs yet; the body and response fields come from the 3.0 API specification and the LEM web 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.


### Request Body

```json
{
  "clientName": "string",
  "groupIds": [
    "string"
  ],
  "expiryDate": 0,
  "tokenTtlMinutes": 0
}
```

---

## Rename Device OAuth Client

**PUT** `{{LEM_URL}}/api/v1/device/{{deviceID}}/oauth-clients/{{oauth_client_id}}`

> **New in 3.0.**

# Rename Device OAuth Client

Renames an OAuth client. `clientName` is the only field that can change; groups, token lifetime and expiry are fixed at creation.
## Endpoint

```http
PUT {{LEM_URL}}/api/v1/device/{{deviceID}}/oauth-clients/{{oauth_client_id}}
```
## Authentication

API key in a request header (case sensitive). The value is the LEM admin API token.

| URL prefix | Auth header |
|---|---|
| `{{LEM_URL}}/api/v1/...` (main fleet API) | `X-AuthToken: <token>` |
| `{{LEM_adminURL}}/admin/v1/...` (admin console, port 8446) | `X-AuthToken: <token>` |
| `{{LEM_URL}}/mpcs/...` (Marketplace Catalog) | `Authorization: <token>` (3.0.x also accepts `X-AuthToken`) |
## Parameters

| Parameter | In | Notes |
|---|---|---|
| `deviceId` | path | **Required.** The edge device. |
| `clientId` | path | **Required.** From `List Device OAuth Clients`. |

## Request body

```json
{
  "clientName": "historian-reader-2"
}
```
## Response

`200 OK`. These are OAuth clients on the **edge device** (LitmusEdge), managed through LEM: LEM relays each call to the device, so the device must be online and run a LitmusEdge version that supports OAuth client management. A client gets an access token from the device's own token endpoint with the client-credentials grant and uses it against that device's APIs.

| Device state | Answer |
|---|---|
| Online, supported | `200` |
| Offline | `503`, `Device '<id>' is offline; OAuth clients can only be managed while the device is online` |
| Version not supported, or not detected yet | `501`, `Device '<id>' does not support OAuth client management` |

## 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
{
  "clientName": "string"
}
```

---

## Regenerate Device OAuth Client Secret

**POST** `{{LEM_URL}}/api/v1/device/{{deviceID}}/oauth-clients/{{oauth_client_id}}/secret`

> **New in 3.0.**

# Regenerate Device OAuth Client Secret

Issues a new secret for an OAuth client and invalidates the old one. The new secret is returned **once, in this response only**. An access token the client already holds keeps working until it expires (at most the client's `tokenTtlMinutes`), so a consumer still using the old secret may only fail on its next token request.
## Endpoint

```http
POST {{LEM_URL}}/api/v1/device/{{deviceID}}/oauth-clients/{{oauth_client_id}}/secret
```
## Authentication

API key in a request header (case sensitive). The value is the LEM admin API token.

| URL prefix | Auth header |
|---|---|
| `{{LEM_URL}}/api/v1/...` (main fleet API) | `X-AuthToken: <token>` |
| `{{LEM_adminURL}}/admin/v1/...` (admin console, port 8446) | `X-AuthToken: <token>` |
| `{{LEM_URL}}/mpcs/...` (Marketplace Catalog) | `Authorization: <token>` (3.0.x also accepts `X-AuthToken`) |
## Parameters

| Parameter | In | Notes |
|---|---|---|
| `deviceId` | path | **Required.** The edge device. |
| `clientId` | path | **Required.** |

## Response

`200 OK`. `clientId`, the new `clientSecret` and `tokenEndpoint`. These are OAuth clients on the **edge device** (LitmusEdge), managed through LEM: LEM relays each call to the device, so the device must be online and run a LitmusEdge version that supports OAuth client management. A client gets an access token from the device's own token endpoint with the client-credentials grant and uses it against that device's APIs.

| Device state | Answer |
|---|---|
| Online, supported | `200` |
| Offline | `503`, `Device '<id>' is offline; OAuth clients can only be managed while the device is online` |
| Version not supported, or not detected yet | `501`, `Device '<id>' does not support OAuth client management` |

## 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.


---

## Delete Device OAuth Client

**DELETE** `{{LEM_URL}}/api/v1/device/{{deviceID}}/oauth-clients/{{oauth_client_id}}`

> **New in 3.0.**

# Delete Device OAuth Client

Deletes an OAuth client, so it can no longer obtain tokens. Tokens it already holds keep working until their TTL runs out (at most the client's `tokenTtlMinutes`).
## Endpoint

```http
DELETE {{LEM_URL}}/api/v1/device/{{deviceID}}/oauth-clients/{{oauth_client_id}}
```
## Authentication

API key in a request header (case sensitive). The value is the LEM admin API token.

| URL prefix | Auth header |
|---|---|
| `{{LEM_URL}}/api/v1/...` (main fleet API) | `X-AuthToken: <token>` |
| `{{LEM_adminURL}}/admin/v1/...` (admin console, port 8446) | `X-AuthToken: <token>` |
| `{{LEM_URL}}/mpcs/...` (Marketplace Catalog) | `Authorization: <token>` (3.0.x also accepts `X-AuthToken`) |
## Parameters

| Parameter | In | Notes |
|---|---|---|
| `deviceId` | path | **Required.** The edge device. |
| `clientId` | path | **Required.** |

## Response

`200 OK`. These are OAuth clients on the **edge device** (LitmusEdge), managed through LEM: LEM relays each call to the device, so the device must be online and run a LitmusEdge version that supports OAuth client management. A client gets an access token from the device's own token endpoint with the client-credentials grant and uses it against that device's APIs.

| Device state | Answer |
|---|---|
| Online, supported | `200` |
| Offline | `503`, `Device '<id>' is offline; OAuth clients can only be managed while the device is online` |
| Version not supported, or not detected yet | `501`, `Device '<id>' does not support OAuth client management` |

## 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.


---