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 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.
The current ETag of the device, required in the If-Match header. Obtain it from GET | List a device.
The device must be active. Write operations on an inactive device return 409. To activate it, access 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.

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: 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 and 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 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. 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. 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 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.