---
title: "PATCH | Update device"
slug: "api-v2-patch-update-device"
updated: 2026-11-03T14:47:51Z
published: 2026-11-03T14:47:51Z
canonical: "docs.senhasegura.io/api-v2-patch-update-device"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.senhasegura.io/llms.txt
> Use this file to discover all available pages before exploring further.

# PATCH | Update device

## Description

Update selected fields of a device registered in PAM Core using the v2 API. The endpoint follows JSON Merge Patch semantics (RFC 7396): only the fields you send are changed, and the fields you omit are preserved. To replace the entire device, access [PUT | Update device](/v4-2/docs/api-v2-put-update-device) instead.

              Info

              

This endpoint belongs to the A2A API v2 surface and is available from Segura™ version 4.2.9. Devices are served from the `/api/v2/platform` base path, not from `/api/v2/pam` like other v2 resources. There is no v1 equivalent: v1 offered no partial update.

---

## Prerequisites

- Authorization with **write** permission to PAM Core granted by the administrator in A2A. For more information, access [How to manage authorizations in A2A](/v4-2/docs/api-v2-how-to-manage-authorizations-in-a2a).
- The current `ETag` of the device, required in the `If-Match` header. Obtain it from [GET | List a device](/v4-2/docs/api-v2-get-list-a-device).
- The device must be active. Write operations on an inactive device return `409`. To activate it, access [POST | Activate device](/v4-2/docs/api-v2-post-activate-device).

---

## Request

`PATCH` `/api/v2/platform/devices/{id}`

### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer | Yes | Unique identification code of the device. **Note:** this value is assigned by Segura™ in [POST \| Create device](/v4-2/docs/api-v2-post-create-device). |

### Request headers

| Header | Required | Description |
| --- | --- | --- |
| `Content-Type` | Yes | Must be `application/merge-patch+json`. Any other media type returns `415`. |
| `If-Match` | Yes | Current `ETag` of the device, for optimistic concurrency. A missing header returns `428`; a value that no longer matches the current state returns `412`. |

### Request body

Every field is optional. A field you send replaces the current value; a field you send as `null` removes the value; a field you omit is left untouched. Array fields are replaced as a whole, not merged item by item.

| Field | Type | Description |
| --- | --- | --- |
| `name` | string | Name that identifies the device. Blocked while a session for the device is active on the proxy. |
| `address` | string | IP address, hostname, or management URL. Blocked while a session for the device is active on the proxy. |
| `type` | string | Device type, by name. Must be a registered type. |
| `vendor` | string | Device vendor, by name. Must be a registered vendor. |
| `product` | string | Device product, by name. Must be a registered product, bound to the vendor. |
| `site` | string | Site where the device is located, by name. Must be a registered site. |
| `domain_name` | string | Domain associated with the device, by name. Send `null` to remove it. |
| `tags` | array[string] | Tags associated with the device. Replaces the whole list. |
| `criticality` | string | Criticality level. Allowed values: `low`, `medium`, `high`. Send `null` to remove it. |
| `enable_remote_app` | boolean | Enables remote application support for the device. |
| `network_connector_id` | integer | Identification code of the Network Connector agent. Send `null` to remove the association. The response expands it into an object. |
| `administrator_group_id` | integer | Identification code of the administrator group. Valid **only** when the access policy mode is static by device; sending it in dynamic policy mode returns `422`. Send `null` to remove it. |
| `owner` | string | Username of the registered user who owns the device. Send `null` to remove it. |
| `connectivities` | array of objects | Connectivity protocols, as `{ protocol, port }`. Replaces the whole list. Allowed protocols: `SSH`, `RDP`, `HTTPS`, `VNC`, `Telnet`, `SQL_Server`. |
| `session_settings` | array of objects | Session automation settings, as `{ connectivity, expected_expression, fill_in_value }`. Replaces the whole list. `connectivity` must match a protocol present in `connectivities`. |

              Attention

              

`id` and `active` cannot be modified through this endpoint and return `422` (`patch.field.not_allowed`). Change the active state with [POST | Activate device](/v4-2/docs/api-v2-post-activate-device) or [POST | Deactivate device](/v4-2/docs/api-v2-post-deactivate-device).

---

### Example request

`PATCH` `{{url}}/api/v2/platform/devices/55`

#### Headers

```
Content-Type: application/merge-patch+json
If-Match: "v3"
```

#### Body

```
{
    "criticality": "low",
    "tags": ["prod", "finance", "critical"],
    "domain_name": null
}
```

---

## Response

```
HTTP/1.1 200 OK
ETag: "v4"
```

The `ETag` header holds the new version of the device. Use this value in the `If-Match` header of the next write operation.

### Example response body

The response returns the complete device in the same format as [GET | List a device](/v4-2/docs/api-v2-get-list-a-device), including the fields the request didn't touch.

```
{
    "data": {
        "id": "55",
        "device": {
            "name": "db-prod-01",
            "address": "10.10.10.10",
            "active": true,
            "type": "Server",
            "vendor": "Oracle",
            "product": "Oracle Linux VM",
            "site": "SP-DC1",
            "domain_name": null,
            "tags": ["prod", "finance", "critical"],
            "criticality": "low",
            "owner": {
                "name": "John Doe"
            },
            "administrator_group": null,
            "enable_remote_app": true,
            "network_connector": {
                "id": "12",
                "name": "NC-SP-01",
                "port": "50001"
            },
            "connectivities": [
                {
                    "protocol": "SSH",
                    "port": 22,
                    "connectable": true
                }
            ],
            "session_settings": [
                {
                    "connectivity": "SSH",
                    "expected_expression": "$",
                    "fill_in_value": "sudo su"
                }
            ]
        }
    },
    "meta": {
        "links": {
            "self": "/api/v2/platform/devices/55"
        },
        "actions": {
            "deactivate": "/api/v2/platform/devices/55/deactivate"
        }
    }
}
```

---

## Response body fields

The response returns the updated device with the same fields as [GET | List a device](/v4-2/docs/api-v2-get-list-a-device). Access that article for the full field tables.

| Field | Type | Description |
| --- | --- | --- |
| `data` | object | The updated device. |
| `data.id` | string | Unique identification code of the device. |
| `data.device` | object | Canonical attributes of the device after the update. |
| `meta` | object | Navigation links and available actions. |
| `meta.links.self` | string | URL of the device. |
| `meta.actions` | object | Actions available for the device in its current state. |

---

## Errors

| HTTP code | Message | Possible cause | Solution |
| --- | --- | --- | --- |
| `400` | `api.request.malformed` | The body isn't valid JSON. | Check the payload syntax. |
| `401` | `api.auth.token.invalid` | The access token is missing or has expired. | Request a new access token. |
| `403` | `api.permission.denied` | The authorization doesn't have write permission to PAM Core resources. | Ask the administrator to check the authorization permissions in A2A, then generate a new token. |
| `404` | `api.resource.not_found` | The device doesn't exist, or it belongs to another tenant. | Check the identification code sent in the path. |
| `409` | `api.resource.conflict.active_sessions` | A session for the device is active on the proxy, which blocks changes to `name` and `address`. | Wait for the session to end, or terminate it, then resend the request. |
| `409` | `api.resource.inactive` | The device is inactive, so write operations are not allowed. | Activate the device with [POST \| Activate device](/v4-2/docs/api-v2-post-activate-device) and resend the request. |
| `412` | `api.precondition.failed` | The `If-Match` value doesn't match the current `ETag`: the device changed after you read it. | Retrieve the device again to get the current `ETag`, reapply your changes, and resend the request. |
| `415` | `Unsupported Media Type` | The `Content-Type` header isn't `application/merge-patch+json`. | Send the correct media type. |
| `428` | `api.precondition.required` | The `If-Match` header is missing. | Send the current `ETag` in the `If-Match` header. |
| `422` | `patch.field.not_allowed` | The body includes `id` or `active`. | Remove the field. Use the activate and deactivate actions to change the state. |
| `422` | `api.validation.invalid_reference` | A referenced type, vendor, product, site, domain, Network Connector, or user doesn't exist; a `session_settings` protocol isn't declared in `connectivities`; or `administrator_group_id` was sent while the access policy mode is dynamic. | Register the value first, or remove the field. Check `error.details` to identify the field. |
| `422` | `api.enum.invalid_value` | `criticality` received a value outside `low`, `medium`, `high`. | Send one of the allowed values. |
| `429` | `rate_limit_exceeded` | The request rate limit was exceeded. | Wait the number of seconds given in the `Retry-After` header, then retry. |
| `500` | `api.internal.error` | Internal server error. | Contact the Segura™ support team. |

### Example error response

`422` a forbidden field was sent in the body:

```
{
    "error": {
        "code": "patch.field.not_allowed",
        "message": "Field 'active' cannot be modified via PATCH."
    }
}
```

### Authentication errors

| Message | Possible cause | Solution |
| --- | --- | --- |
| `Client authentication failed.` | Application authentication failure with the Segura™ server. | Check the authentication parameters (`Access Token URL`, `Client ID`, and `Client secret`) and request a new access token. |
| `Invalid signature` | Failure in recognizing the client application URL. | Check the URL of the client application and resend the request. |
| `No route matched with those values.` | Missing authorization header in the API request. | Request a new access token. |
| `Request timed out.` | The request exceeded the timeout limit. | Check the connectivity between the source of the request and the Segura™ server. |

---

## Related documents

- [API v2 — Conventions and shared behaviors](/v4-2/docs/api-v2-conventions-and-shared-behaviors)
- [PUT | Update device](/v4-2/docs/api-v2-put-update-device)
- [GET | List a device](/v4-2/docs/api-v2-get-list-a-device)
- [POST | Create device](/v4-2/docs/api-v2-post-create-device)
- [How to manage authorizations in A2A](/v4-2/docs/api-v2-how-to-manage-authorizations-in-a2a)