---
title: "GET | Listar todos os dispositivos"
slug: "api-v2-get-list-all-devices"
updated: 2026-11-03T14:47:51Z
published: 2026-11-03T14:47:51Z
canonical: "docs.senhasegura.io/api-v2-get-list-all-devices"
---

> ## 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 todos os dispositivos

## Descrição

Liste os dispositivos associados à sua autorização no PAM Core, utilizando o modelo canônico v2. Retorna uma projeção paginada e filtrável da entidade `DeviceV2`.

              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 todos os dispositivos](/v4-2/docs/api-get-list-all-devices).

---

## 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).

---

## Requisição

`GET` `/api/v2/platform/devices`

### Parâmetros de query

Todos os parâmetros de query são opcionais. Quando nenhum é informado, o endpoint retorna a primeira página de todos os dispositivos acessíveis à autorização, utilizando a projeção de listagem definida no schema de resposta.

#### Filtros

Os filtros são combinados com lógica AND: o dispositivo precisa atender a todos os filtros informados.

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `name` | string | Filtra pelo nome do dispositivo. Correspondência exata. |
| `address` | string | Filtra pelo endereço IP, hostname ou URL de gerenciamento. Correspondência exata. |
| `active` | boolean | Filtra pelo estado operacional. Valores aceitos: `true`, `false`. |
| `type` | string | Filtra pelo tipo de dispositivo. Correspondência exata com um tipo cadastrado. Veja [Tipos](/v4-2/docs/pam-device-types). |
| `vendor` | string | Filtra pelo fabricante. Correspondência exata com um fabricante cadastrado. Veja [Fabricantes](/v4-2/docs/pam-device-vendors). |
| `product` | string | Filtra pelo modelo. Correspondência exata com um modelo cadastrado. Veja [Modelos](/v4-2/docs/pam-device-products). |
| `site` | string | Filtra pelo site. Correspondência exata com um site cadastrado. Veja [Sites](/v4-2/docs/pam-device-sites). |
| `domain_name` | string | Filtra pelo nome de domínio. Correspondência exata. Omita este parâmetro para retornar dispositivos independentemente de associação a domínio. |
| `tags` | array[string] | Filtra por uma ou mais tags. Use valores separados por vírgula para lógica OR (`tags=prod,database`); repita o parâmetro para lógica AND (`tags=prod&tags=database`). |
| `search` | string | Realiza uma busca de texto livre no inventário de dispositivos. |

#### Ordenação

`sort_by` aceita um ou mais campos no formato `campo:asc` ou `campo:desc`. Múltiplos campos são separados por vírgula e processados da esquerda para a direita. A direção padrão é `asc`. Exemplo: `sort_by=name:asc,type:desc`.

Campos ordenáveis: `name`, `type`, `vendor`, `product`, `site`.

Um campo não suportado retorna `422` (`api.sort.invalid_field`), com uma indicação dos campos permitidos; uma direção não suportada retorna `422` (`api.sort.invalid_direction`). Para as regras completas de ordenação, consulte [API v2 - Convenções e comportamentos compartilhados](/v4-2/docs/api-v2-conventions-and-shared-behaviors).

#### Projeção de campos

`fields` restringe a resposta aos campos informados, utilizando caminhos com namespace. Exemplo: `fields=id,device.name,device.address`.

O campo `data[].id` é sempre retornado, mesmo que a projeção não o solicite. Um caminho que não existe na projeção de listagem retorna `422` (`api.fields.invalid`).

#### Paginação

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `page` | integer | Número da página. Mínimo: `1`. Padrão: `1`. |
| `limit` | integer | Resultados por página. Mínimo: `1`. Máximo: `200`. Padrão: `50`. |

Um `limit` acima de `200` retorna `422` (`api.pagination.limit.exceeded`), e `page=0` retorna `422` (`api.request.invalid_param`). Uma página além da última retorna `200` com o array `data` vazio e metadados de paginação coerentes.

---

### Exemplo de requisição

`GET` `{{url}}/api/v2/platform/devices?vendor=Oracle&active=true&sort_by=name:asc&limit=50`

---

## Resposta

```
HTTP/1.1 200 OK
```

Toda resposta traz o cabeçalho `X-Request-Id`, que correlaciona a requisição nos logs do Segura™.

### 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"]
            }
        },
        {
            "id": "56",
            "device": {
                "name": "ws-dev-04",
                "address": "10.20.30.40",
                "active": false,
                "type": "Workstation",
                "vendor": "Microsoft",
                "product": "Windows Server 2022",
                "site": "NY-DC2",
                "domain_name": null,
                "tags": []
            }
        }
    ],
    "meta": {
        "pagination": {
            "page": 1,
            "limit": 50,
            "total_items": 340,
            "total_pages": 7
        },
        "links": {
            "self": "/api/v2/platform/devices?page=1&limit=50",
            "first": "/api/v2/platform/devices?page=1&limit=50",
            "next": "/api/v2/platform/devices?page=2&limit=50",
            "last": "/api/v2/platform/devices?page=7&limit=50"
        }
    }
}
```

---

## Campos do corpo da resposta

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `data` | array de objetos | Lista de dispositivos que atendem aos filtros da requisição. Retorna um array vazio quando nenhum dispositivo corresponde. |
| `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 do dispositivo incluídos na projeção de listagem. |
| `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. |
| `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. |
| `meta` | object | Metadados de paginação e links de navegação. |
| `meta.pagination` | object | Detalhes de paginação do conjunto de resultados atual. |
| `meta.pagination.page` | integer | Número da página atual. |
| `meta.pagination.limit` | integer | Número máximo de resultados por página. |
| `meta.pagination.total_items` | integer | Número total de dispositivos que atendem aos filtros. |
| `meta.pagination.total_pages` | integer | Número total de páginas. |
| `meta.links` | object | Links de navegação para paginar os resultados. |
| `meta.links.self` | string | URL da página atual. |
| `meta.links.first` | string | URL da primeira página. |
| `meta.links.next` | string | URL da próxima página. |
| `meta.links.last` | string | URL da última página. |

              Info

              

A projeção de listagem é um subconjunto do modelo canônico. Campos como `criticality`, `owner`, `administrator_group`, `network_connector`, `enable_remote_app`, `connectivities` e `session_settings` são retornados apenas pelo endpoint de detalhe. Para obtê-los, acesse [GET | Listar um dispositivo (v2)](/v4-2/docs/api-v2-get-list-a-device).

---

## 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. |
| `422` | `api.pagination.limit.exceeded` | O `limit` está acima do máximo de `200`. | Reduza o `limit` para `200` ou menos e pagine os resultados. |
| `422` | `api.request.invalid_param` | O `page` é `0` ou está fora do intervalo permitido. | Envie um valor de `page` igual ou maior que `1`. |
| `422` | `api.sort.invalid_field` | O `sort_by` referencia um campo fora do conjunto ordenável. | Ordene por `name`, `type`, `vendor`, `product` ou `site`. |
| `422` | `api.sort.invalid_direction` | O `sort_by` usa uma direção diferente de `asc` ou `desc`. | Use `campo:asc` ou `campo:desc`. |
| `422` | `api.fields.invalid` | O `fields` referencia um caminho fora da projeção de listagem. | Verifique os caminhos dos campos no schema de resposta. |
| `429` | `rate_limit_exceeded` | O limite de requisições do tenant, da aplicação ou do endpoint foi excedido. | Aguarde o número de segundos indicado no cabeçalho `Retry-After` e tente novamente. |
| `500` | `api.internal.error` | Erro interno do servidor. | Entre em contato com a equipe de suporte da Segura™. |

### Exemplo de resposta de erro

`422` um campo solicitado na projeção não existe:

```
{
    "error": {
        "code": "api.fields.invalid",
        "message": "One or more requested fields do not exist in the resource schema."
    }
}
```

### 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™. |

Para a política de `403` versus `404` aplicada a recursos fora do escopo da sua autorização, consulte [API v2 - Convenções e comportamentos compartilhados](/v4-2/docs/api-v2-conventions-and-shared-behaviors).

---

## Documentos relacionados

- [API v2 - Convenções e comportamentos compartilhados](/v4-2/docs/api-v2-conventions-and-shared-behaviors)
- [GET | Listar um dispositivo (v2)](/v4-2/docs/api-v2-get-list-a-device)
- [POST | Criar dispositivo (v2)](/v4-2/docs/api-v2-post-create-device)
- [GET | Listar status de conexão do dispositivo (v2)](/v4-2/docs/api-v2-get-device-connection-status)
- [Como gerenciar autorizações no A2A API v2](/v4-2/docs/api-v2-how-to-manage-authorizations-in-a2a)
- [Cadastro de dispositivo](/v4-2/docs/pam-device-device-registration)