---
title: "GET | List a device"
slug: "api-v2-get-list-a-device"
updated: 2026-11-03T14:47:51Z
published: 2026-11-03T14:47:51Z
canonical: "docs.senhasegura.io/api-v2-get-list-a-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.

# GET | List a device

## Description

Access the complete canonical model of a device registered in PAM Core, using the v2 API. Unlike the list endpoint, this endpoint returns every field of the `DeviceV2` entity, including `criticality`, `owner`, `administrator_group`, `network_connector`, `connectivities`, and `session_settings`.

              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. The v1 equivalent is documented in [GET | List a device by [id]](/v4-2/docs/api-get-list-a-device).

---

## Prerequisites

- Authorization with **read** 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).
- An existing device. To create one, access [POST | Create device](/v4-2/docs/api-v2-post-create-device).

---

## Request

`GET` `/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), which returns it as a string in the response body. |

### Query parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `fields` | string | No | Restricts the response to the listed fields, using namespaced paths. Example: `fields=device.name,device.connectivities`. `data.id` is always returned, whether or not the projection requests it. A path that doesn't exist in the canonical model returns `422`. |

### Request headers

| Header | Required | Description |
| --- | --- | --- |
| `If-None-Match` | No | Conditional read. Send the `ETag` from a previous response to receive `304 Not Modified` when the device hasn't changed. For more information, access [API v2 — Conventions and shared behaviors](/v4-2/docs/api-v2-conventions-and-shared-behaviors). |

---

### Example request

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

---

## Response

```
HTTP/1.1 200 OK
```

The response carries a strong `ETag` header representing the current state of the device, and an `X-Request-Id` header that correlates the request across Segura™ logs. Save the `ETag`: it's required in the `If-Match` header of [PUT | Update device](/v4-2/docs/api-v2-put-update-device) and [PATCH | Update device](/v4-2/docs/api-v2-patch-update-device).

Every field of the canonical model is returned, including fields whose value is `null`. An inactive device returns `200` with `active` set to `false`.

### Example response body

```
{
    "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": "high",
            "owner": {
                "name": "John Doe"
            },
            "administrator_group": {
                "id": "5",
                "name": "PAM Admins"
            },
            "enable_remote_app": true,
            "network_connector": {
                "id": "12",
                "name": "NC-SP-01",
                "port": "50001"
            },
            "connectivities": [
                {
                    "protocol": "SSH",
                    "port": 22,
                    "connectable": true
                },
                {
                    "protocol": "RDP",
                    "port": 3389,
                    "connectable": false
                }
            ],
            "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

| Field | Type | Description |
| --- | --- | --- |
| `data` | object | Device returned by the request. |
| `data.id` | string | Unique identification code of the device, assigned by Segura™ in [POST \| Create device](/v4-2/docs/api-v2-post-create-device). Always present in the response. |
| `data.device` | object | Canonical device attributes. |
| `data.device.name` | string | Name that identifies the device. |
| `data.device.address` | string | IP address, hostname, or management URL of the device. |
| `data.device.active` | boolean | Indicates whether the device is active. Changed through [POST \| Activate device](/v4-2/docs/api-v2-post-activate-device) and [POST \| Deactivate device](/v4-2/docs/api-v2-post-deactivate-device), never by an update. |
| `data.device.type` | string | Device type. Registered in [Device types](/v4-2/docs/pam-device-types). |
| `data.device.vendor` | string | Device vendor. Registered in [Device vendors](/v4-2/docs/pam-device-vendors). |
| `data.device.product` | string | Device product, bound to the vendor. Registered in [Device products](/v4-2/docs/pam-device-products). |
| `data.device.site` | string | Site where the device is located. Registered in [Device sites](/v4-2/docs/pam-device-sites). |
| `data.device.domain_name` | string | Domain associated with the device. Returns `null` when the device isn't linked to a domain. |
| `data.device.tags` | array[string] | Tags associated with the device. Returns an empty array when no tags are configured. |
| `data.device.criticality` | string | Criticality level of the device. Possible values: `low`, `medium`, `high`. Returns `null` when not configured. |
| `data.device.owner` | object | User who owns the device. Returns `null` when no owner is configured. |
| `data.device.owner.name` | string | Name of the device owner. |
| `data.device.administrator_group` | object | Administrator group associated with the device. Applies only when the access policy mode is static by device. Returns `null` when not configured. |
| `data.device.administrator_group.id` | string | Unique identification code of the administrator group. Use this value in the `administrator_group_id` field when updating the device. |
| `data.device.administrator_group.name` | string | Name of the administrator group. |
| `data.device.enable_remote_app` | boolean | Indicates whether remote application support is enabled for the device. |
| `data.device.network_connector` | object | Network Connector used to reach the device. Returns `null` when the device isn't associated with one. For more information, access [How to configure devices on Network Connector](/v4-2/docs/network-connector-how-to-configure-devices-on-network-connector). |
| `data.device.network_connector.id` | string | Unique identification code of the Network Connector agent. |
| `data.device.network_connector.name` | string | Name of the Network Connector. |
| `data.device.network_connector.port` | string | Port of the Network Connector agent through which the device is reached. This is the agent port, not the broker port. |
| `data.device.connectivities` | array of objects | Connectivity protocols configured on the device. |
| `data.device.connectivities[].protocol` | string | Connectivity protocol. Possible values: `SSH`, `RDP`, `HTTPS`, `VNC`, `Telnet`, `SQL_Server`. |
| `data.device.connectivities[].port` | integer | Port used by the protocol. |
| `data.device.connectivities[].connectable` | boolean | Result of the most recent connectivity test for this protocol. For the full test result, access [GET \| List device connection status](/v4-2/docs/api-v2-get-device-connection-status). |
| `data.device.session_settings` | array of objects | Session automation settings applied when a session starts. |
| `data.device.session_settings[].connectivity` | string | Protocol the setting applies to. Matches one of the protocols in `connectivities`. |
| `data.device.session_settings[].expected_expression` | string | Expression the session waits for before sending `fill_in_value`. Returns `null` when not configured. |
| `data.device.session_settings[].fill_in_value` | string | Value sent when `expected_expression` is matched. Returns `null` when not configured. |
| `meta` | object | Navigation links and available actions. |
| `meta.links` | object | Navigation links for the device. |
| `meta.links.self` | string | URL of the device. |
| `meta.actions` | object | Actions available for the device in its current state. |

              Info

              

`meta.actions` reflects the current state of the device: an active device exposes only `deactivate`, and an inactive device exposes only `activate`. The connection-status endpoint is a query rather than an action, so it never appears here.

---

## Errors

| HTTP code | Message | Possible cause | Solution |
| --- | --- | --- | --- |
| `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 read permission to PAM Core resources. | Ask the administrator to check the authorization permissions in A2A, then generate a new token. |
| `403` | `api.fields.sensitive.not_allowed` | `fields` requests a field classified as sensitive. | Remove the sensitive field from the projection. |
| `404` | `api.resource.not_found` | The device doesn't exist, or it belongs to another tenant. | Check the `id`. For the `403` versus `404` policy, access [API v2 — Conventions and shared behaviors](/v4-2/docs/api-v2-conventions-and-shared-behaviors). |
| `422` | `api.fields.invalid` | `fields` references a path outside the canonical model. | Check the field paths against the response schema. |
| `500` | `api.internal.error` | Internal server error. | Contact the Segura™ support team. |

### Example error response

`404` the device doesn't exist or is outside the authorization scope:

```
{
    "error": {
        "code": "api.resource.not_found",
        "message": "The requested resource does not exist or is not accessible."
    }
}
```

### 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)
- [GET | List all devices](/v4-2/docs/api-v2-get-list-all-devices)
- [GET | List device connection status](/v4-2/docs/api-v2-get-device-connection-status)
- [PUT | Update device](/v4-2/docs/api-v2-put-update-device)
- [PATCH | Update device](/v4-2/docs/api-v2-patch-update-device)
- [How to manage authorizations in A2A](/v4-2/docs/api-v2-how-to-manage-authorizations-in-a2a)