--- title: "PUT | Update device" slug: "api-v2-put-update-device" updated: 2026-11-03T14:47:51Z published: 2026-11-03T14:47:51Z canonical: "docs.senhasegura.io/api-v2-put-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. # PUT | Update device ## Description Replace the full representation of a device registered in PAM Core using the v2 API. This endpoint overwrites every mutable field of the device: optional fields left out of the request are reset to their default or emptied. To change only some fields, access [PATCH | Update device](/v4-2/docs/api-v2-patch-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. In v1, updating a device reused the create endpoint; v2 separates full replacement (`PUT`) from partial update (`PATCH`). --- ## 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 `PUT` `/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 | | --- | --- | --- | | `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 The body takes the same shape and the same required fields as [POST | Create device](/v4-2/docs/api-v2-post-create-device): `name`, `address`, `type`, `vendor`, `product`, and `site` are mandatory, and the optional fields are `domain_name`, `tags`, `criticality`, `enable_remote_app`, `network_connector_id`, `administrator_group_id`, `owner`, `connectivities`, and `session_settings`. Access that article for the full field table. Read-only fields are ignored when sent: `id`, `active`, and `connectable`. The active state is changed only through [POST | Activate device](/v4-2/docs/api-v2-post-activate-device) and [POST | Deactivate device](/v4-2/docs/api-v2-post-deactivate-device). Attention `PUT` replaces the whole device. Every optional field you omit is **reset**, not preserved: `tags` and `connectivities` become empty, `enable_remote_app` returns to `false`, and `criticality` returns to `medium`. Send the complete representation, or use [PATCH | Update device](/v4-2/docs/api-v2-patch-update-device) to change individual fields. Changing `name` or `address` is blocked while a session for the device is active on the proxy, which returns `409`. --- ### Example request `PUT` `{{url}}/api/v2/platform/devices/55` #### Headers ``` Content-Type: application/json If-Match: "v3" ``` #### Body ``` { "name": "db-prod-01", "address": "10.10.10.10", "type": "Server", "vendor": "Oracle", "product": "Oracle Linux VM", "site": "SP-DC1", "domain_name": "CORP", "tags": ["prod", "database"], "criticality": "medium", "enable_remote_app": true, "network_connector_id": 12, "owner": "jdoe", "connectivities": [ { "protocol": "SSH", "port": 22 } ] } ``` --- ## 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). In the example below, `session_settings` was omitted from the request and has therefore been reset to an empty array. ``` { "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": "CORP", "tags": ["prod", "database"], "criticality": "medium", "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": [] } }, "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 and the `Content-Type` header. | | `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. | | `409` | `api.resource.conflict.duplicate_address` | Another device already uses the management address sent in `address`. | Use a different address. | | `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. | | `428` | `api.precondition.required` | The `If-Match` header is missing. | Send the current `ETag` in the `If-Match` header. | | `422` | `api.validation.required_field` | A required field is missing. | Send `name`, `address`, `type`, `vendor`, `product`, and `site`. | | `422` | `api.validation.invalid_reference` | A referenced type, vendor, product, site, domain, Network Connector, or user doesn't exist, 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 `412` the device changed after it was read: ``` { "error": { "code": "api.precondition.failed", "message": "The If-Match header does not match the current ETag." } } ``` ### 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) - [PATCH | Update device](/v4-2/docs/api-v2-patch-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)