---
title: "GET | Listar um dispositivo"
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 | Listar um dispositivo

## Descrição

Acesse o modelo canônico completo de um dispositivo cadastrado no PAM Core, utilizando a API v2. Diferente do endpoint de listagem, este endpoint retorna todos os campos da entidade `DeviceV2`, incluindo `criticality`, `owner`, `administrator_group`, `network_connector`, `connectivities` e `session_settings`.

              Info

              

Este endpoint faz parte da superfície da API v2 do A2A e está disponível a partir da versão 4.2.9 do Segura™. Os dispositivos são servidos pelo caminho base `/api/v2/platform`, e não por `/api/v2/pam` como os demais recursos v2. O equivalente v1 está documentado em [GET | Listar um dispositivo por [id]](/v4-2/docs/api-get-list-a-device).

---

## Pré-requisitos

- Autorização com permissão de **leitura** para o PAM Core, concedida pelo administrador no A2A. Para mais informações, acesse [Como gerenciar autorizações no A2A API v2](/v4-2/docs/api-v2-how-to-manage-authorizations-in-a2a).
- Um dispositivo existente. Para criar um, acesse [POST | Criar dispositivo (v2)](/v4-2/docs/api-v2-post-create-device).

---

## Requisição

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

### Parâmetros de caminho

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | integer | Sim | Código de identificação único do dispositivo. **Nota:** este valor é atribuído pelo Segura™ em [POST \| Criar dispositivo (v2)](/v4-2/docs/api-v2-post-create-device), que o retorna como string no corpo da resposta. |

### Parâmetros de query

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `fields` | string | Não | Restringe a resposta aos campos informados, utilizando caminhos com namespace. Exemplo: `fields=device.name,device.connectivities`. O campo `data.id` é sempre retornado, mesmo que a projeção não o solicite. Um caminho que não existe no modelo canônico retorna `422`. |

### Cabeçalhos

| Cabeçalho | Obrigatório | Descrição |
| --- | --- | --- |
| `If-None-Match` | Não | Leitura condicional. Envie o `ETag` de uma resposta anterior para receber `304 Not Modified` quando o dispositivo não tiver sido alterado. Para mais informações, acesse [API v2 - Convenções e comportamentos compartilhados](/v4-2/docs/api-v2-conventions-and-shared-behaviors). |

---

### Exemplo de requisição

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

---

## Resposta

```
HTTP/1.1 200 OK
```

A resposta traz um cabeçalho `ETag` forte, que representa o estado atual do dispositivo, e um cabeçalho `X-Request-Id`, que correlaciona a requisição nos logs do Segura™. Guarde o `ETag`: ele é obrigatório no cabeçalho `If-Match` de [PUT | Atualizar dispositivo (v2)](/v4-2/docs/api-v2-put-update-device) e [PATCH | Atualizar dispositivo (v2)](/v4-2/docs/api-v2-patch-update-device).

Todos os campos do modelo canônico são retornados, inclusive aqueles cujo valor é `null`. Um dispositivo inativo retorna `200` com `active` igual a `false`.

### Exemplo de corpo da resposta

```
{
    "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"
        }
    }
}
```

---

## Campos do corpo da resposta

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `data` | object | Dispositivo retornado pela requisição. |
| `data.id` | string | Código de identificação único do dispositivo, atribuído pelo Segura™ em [POST \| Criar dispositivo (v2)](/v4-2/docs/api-v2-post-create-device). Sempre presente na resposta. |
| `data.device` | object | Atributos canônicos do dispositivo. |
| `data.device.name` | string | Nome que identifica o dispositivo. |
| `data.device.address` | string | Endereço IP, hostname ou URL de gerenciamento do dispositivo. |
| `data.device.active` | boolean | Indica se o dispositivo está ativo. Alterado por [POST \| Ativar dispositivo (v2)](/v4-2/docs/api-v2-post-activate-device) e [POST \| Desativar dispositivo (v2)](/v4-2/docs/api-v2-post-deactivate-device), nunca por uma atualização. |
| `data.device.type` | string | Tipo do dispositivo. Cadastrado em [Tipos](/v4-2/docs/pam-device-types). |
| `data.device.vendor` | string | Fabricante do dispositivo. Cadastrado em [Fabricantes](/v4-2/docs/pam-device-vendors). |
| `data.device.product` | string | Modelo do dispositivo, vinculado ao fabricante. Cadastrado em [Modelos](/v4-2/docs/pam-device-products). |
| `data.device.site` | string | Site onde o dispositivo está localizado. Cadastrado em [Sites](/v4-2/docs/pam-device-sites). |
| `data.device.domain_name` | string | Domínio associado ao dispositivo. Retorna `null` quando o dispositivo não está vinculado a um domínio. |
| `data.device.tags` | array[string] | Tags associadas ao dispositivo. Retorna um array vazio quando nenhuma tag está configurada. |
| `data.device.criticality` | string | Nível de criticidade do dispositivo. Valores possíveis: `low`, `medium`, `high`. Retorna `null` quando não configurado. |
| `data.device.owner` | object | Usuário responsável pelo dispositivo. Retorna `null` quando nenhum responsável está configurado. |
| `data.device.owner.name` | string | Nome do responsável pelo dispositivo. |
| `data.device.administrator_group` | object | Grupo administrador associado ao dispositivo. Aplica-se somente quando o modo de política de acesso é estático por dispositivo. Retorna `null` quando não configurado. |
| `data.device.administrator_group.id` | string | Código de identificação único do grupo administrador. Use este valor no campo `administrator_group_id` ao atualizar o dispositivo. |
| `data.device.administrator_group.name` | string | Nome do grupo administrador. |
| `data.device.enable_remote_app` | boolean | Indica se o suporte a aplicação remota está habilitado para o dispositivo. |
| `data.device.network_connector` | object | Network Connector utilizado para alcançar o dispositivo. Retorna `null` quando o dispositivo não está associado a um. Para mais informações, acesse [Como configurar dispositivos no Network Connector](/v4-2/docs/network-connector-how-to-configure-devices-on-network-connector). |
| `data.device.network_connector.id` | string | Código de identificação único do agent do Network Connector. |
| `data.device.network_connector.name` | string | Nome do Network Connector. |
| `data.device.network_connector.port` | string | Porta do agent do Network Connector pela qual o dispositivo é alcançado. Trata-se da porta do agent, não da porta do broker. |
| `data.device.connectivities` | array de objetos | Protocolos de conectividade configurados no dispositivo. |
| `data.device.connectivities[].protocol` | string | Protocolo de conectividade. Valores possíveis: `SSH`, `RDP`, `HTTPS`, `VNC`, `Telnet`, `SQL_Server`. |
| `data.device.connectivities[].port` | integer | Porta utilizada pelo protocolo. |
| `data.device.connectivities[].connectable` | boolean | Resultado do teste de conectividade mais recente para este protocolo. Para o resultado completo do teste, acesse [GET \| Listar status de conexão do dispositivo (v2)](/v4-2/docs/api-v2-get-device-connection-status). |
| `data.device.session_settings` | array de objetos | Configurações de automação de sessão aplicadas no início de uma sessão. |
| `data.device.session_settings[].connectivity` | string | Protocolo ao qual a configuração se aplica. Corresponde a um dos protocolos em `connectivities`. |
| `data.device.session_settings[].expected_expression` | string | Expressão que a sessão aguarda antes de enviar `fill_in_value`. Retorna `null` quando não configurada. |
| `data.device.session_settings[].fill_in_value` | string | Valor enviado quando `expected_expression` é encontrada. Retorna `null` quando não configurado. |
| `meta` | object | Links de navegação e ações disponíveis. |
| `meta.links` | object | Links de navegação do dispositivo. |
| `meta.links.self` | string | URL do dispositivo. |
| `meta.actions` | object | Ações disponíveis para o dispositivo em seu estado atual. |

              Info

              

O campo `meta.actions` reflete o estado atual do dispositivo: um dispositivo ativo expõe apenas `deactivate`, e um dispositivo inativo expõe apenas `activate`. O endpoint de status de conexão é uma consulta, e não uma ação, por isso nunca aparece aqui.

---

## Erros

| Código HTTP | Mensagem | Causa possível | Solução |
| --- | --- | --- | --- |
| `401` | `api.auth.token.invalid` | O token de acesso está ausente ou expirou. | Solicite um novo token de acesso. |
| `403` | `api.permission.denied` | A autorização não tem permissão de leitura para os recursos do PAM Core. | Peça ao administrador para verificar as permissões da autorização no A2A e gere um novo token. |
| `403` | `api.fields.sensitive.not_allowed` | O `fields` solicita um campo classificado como sensível. | Remova o campo sensível da projeção. |
| `404` | `api.resource.not_found` | O dispositivo não existe ou pertence a outro tenant. | Verifique o `id`. Para a política de `403` versus `404`, acesse [API v2 - Convenções e comportamentos compartilhados](/v4-2/docs/api-v2-conventions-and-shared-behaviors). |
| `422` | `api.fields.invalid` | O `fields` referencia um caminho fora do modelo canônico. | Verifique os caminhos dos campos no schema de resposta. |
| `500` | `api.internal.error` | Erro interno do servidor. | Entre em contato com a equipe de suporte da Segura™. |

### Exemplo de resposta de erro

`404` o dispositivo não existe ou está fora do escopo da autorização:

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

### Erros de autenticação

| Mensagem | Causa possível | Solução |
| --- | --- | --- |
| `Client authentication failed.` | Falha na autenticação da aplicação com o servidor Segura™. | Verifique os parâmetros de autenticação (`Access Token URL`, `Client ID` e `Client secret`) e solicite um novo token de acesso. |
| `Invalid signature` | Falha no reconhecimento da URL da aplicação cliente. | Verifique a URL da aplicação cliente e reenvie a requisição. |
| `No route matched with those values.` | Cabeçalho de autorização ausente na requisição da API. | Solicite um novo token de acesso. |
| `Request timed out.` | A requisição excedeu o limite de tempo. | Verifique a conectividade entre a origem da requisição e o servidor Segura™. |

---

## Documentos relacionados

- [API v2 - Convenções e comportamentos compartilhados](/v4-2/docs/api-v2-conventions-and-shared-behaviors)
- [GET | Listar todos os dispositivos (v2)](/v4-2/docs/api-v2-get-list-all-devices)
- [GET | Listar status de conexão do dispositivo (v2)](/v4-2/docs/api-v2-get-device-connection-status)
- [PUT | Atualizar dispositivo (v2)](/v4-2/docs/api-v2-put-update-device)
- [PATCH | Atualizar dispositivo (v2)](/v4-2/docs/api-v2-patch-update-device)
- [Como gerenciar autorizações no A2A API v2](/v4-2/docs/api-v2-how-to-manage-authorizations-in-a2a)