---
title: "GET | Listar todas as chaves SSH"
slug: "api-v2-get-list-all-ssh-keys"
updated: 2026-11-03T14:47:51Z
published: 2026-11-03T14:47:51Z
canonical: "docs.senhasegura.io/api-v2-get-list-all-ssh-keys"
---

> ## 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 todas as chaves SSH

## Descrição

Liste todas as chaves SSH associadas à sua autorização no PAM Core, utilizando o modelo canônico da API v2. O endpoint retorna uma projeção paginada da entidade `SSHKeyV2` e oferece suporte a filtragem, ordenação e projeção de campos.

Valores secretos nunca são retornados. A resposta informa apenas se há uma chave privada ou uma senha configurada, por meio dos indicadores `secret.has_private_key` e `secret.has_password`.

Info

O equivalente na v1 continua disponível e está documentado em [SSH keys](/v4-2/docs/api-a2a-pam-core-ssh-keys). Os nomes dos campos mudam entre as duas versões: `enabled` na v1 é `ssh_key.active` na v2, `tags` na v1 é `ssh_key.credential_tags` na v2, e o `identifier` da v1 foi substituído pelo `id` atribuído pela Segura™.

---

## Pré-requisitos

Autorização com permissão de **leitura** no PAM Core, concedida pelo administrador no A2A. Para mais informações, acesse [Como gerenciar autorizações no A2A](/v4-2/docs/api-v2-how-to-manage-authorizations-in-a2a).

---

## Requisição

`GET` `/api/v2/pam/ssh-keys`

### Parâmetros de query

Os nomes dos filtros usam notação de ponto que espelha a estrutura da resposta. Apenas `main_device_id` é plano, porque referencia outra entidade por ID.

#### Filtros

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `ssh_key.key_name` | string | Filtra pelo nome da chave. Correspondência exata. |
| `ssh_key.username` | string | Filtra pelo nome de usuário associado à chave. Correspondência exata. |
| `ssh_key.active` | boolean | Filtra pelo status de ativação. Valores aceitos: `true`, `false`. |
| `ssh_key.credential_tags` | array[string] | Filtra por uma ou mais tags. Use valores separados por vírgula para lógica OU; repita o parâmetro para lógica E. |
| `main_device_id` | integer | Filtra pelo ID do dispositivo principal associado à chave. |
| `secret.has_private_key` | boolean | Filtra pela existência de uma chave privada configurada. Valores aceitos: `true`, `false`. |
| `secret.has_password` | boolean | Filtra pela existência de uma senha configurada. Valores aceitos: `true`, `false`. |

A especificação afirma que este filtro é obrigatório. O refinamento de engenharia de 2026-07-15 questionou essa decisão e ela nunca foi fechada. Todos os demais filtros são opcionais.

Solicitar um valor secreto por meio da projeção de campos é rejeitado. Consulte a seção Erros.

#### Ordenação

`sort_by` aceita um ou mais campos da resposta e os valida contra uma lista permitida. Campos inválidos são rejeitados. Para o formato do parâmetro, a sintaxe de direção e a precedência entre múltiplos campos, consulte [API v2 - Conventions and shared behaviors](/v4-2/docs/api-v2-conventions-and-shared-behaviors).

#### Paginação

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

---

### Exemplo de requisição

`GET` `{{url}}/api/v2/pam/ssh-keys?ssh_key.active=true&limit=50`

---

## Resposta

```
HTTP/1.1 200 OK
```

### Exemplo de corpo da resposta

```
{
    "data": [
        {
            "id": "201",
            "key_name": "prod-deploy-key",
            "username": "deploy-user",
            "active": true,
            "main_device": { "id": "55", "hostname": "db-prod-01" },
            "credential_tags": ["prod", "ci-cd"],
            "has_private_key": true,
            "has_password": false,
            "last_used_at": "2026-01-29T12:34:56Z"
        }
    ],
    "meta": {
        "pagination": {
            "page": 1,
            "limit": 50,
            "total_items": 85,
            "total_pages": 2
        },
        "links": {
            "self": "/api/v2/pam/ssh-keys?page=1&limit=50",
            "first": "/api/v2/pam/ssh-keys?page=1&limit=50",
            "next": "/api/v2/pam/ssh-keys?page=2&limit=50",
            "last": "/api/v2/pam/ssh-keys?page=2&limit=50"
        }
    }
}
```

A projeção da listagem é plana. Cada item carrega os campos diretamente, e não dentro dos objetos `ssh_key` e `secret` retornados pelo endpoint de detalhe. Os nomes dos filtros continuam em notação de ponto, portanto `secret.has_private_key` filtra pelo campo que esta resposta retorna como `has_private_key`.

---

## Campos do corpo da resposta

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `data` | array de objetos | Lista de chaves SSH que correspondem aos filtros da requisição. |
| `data[].id` | string | Código único de identificação da chave SSH, atribuído pela Segura™. |
| `data[].key_name` | string | Nome que identifica a chave SSH. |
| `data[].username` | string | Nome de usuário associado à chave SSH. |
| `data[].active` | boolean | Indica se a chave SSH está ativa. |
| `data[].main_device` | object | Dispositivo principal associado à chave SSH. É o dispositivo em que a rotação é executada. |
| `data[].main_device.id` | string | Código único de identificação do dispositivo principal. |
| `data[].main_device.hostname` | string | Hostname do dispositivo principal. |
| `data[].credential_tags` | array[string] | Tags associadas à chave SSH. Retorna um array vazio quando não há tags configuradas. |
| `data[].has_private_key` | boolean | Indica se há uma chave privada configurada para esta chave SSH. Valores secretos nunca são retornados. |
| `data[].has_password` | boolean | Indica se há uma senha configurada para esta chave SSH. Valores secretos nunca são retornados. |
| `data[].last_used_at` | string | Data e hora do último uso registrado, no formato ISO 8601. Exemplo: `2026-01-29T12:34:56Z`. Retorna `null` quando a chave não tem uso registrado. |
| `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 chaves SSH que correspondem aos filtros. |
| `meta.pagination.total_pages` | integer | Número total de páginas. |
| `meta.links` | object | Links de navegação para percorrer os resultados. |
| `meta.links.self` | string | URL da página atual, incluindo a query string enviada na requisição. |
| `meta.links.first` | string | URL da primeira página. |
| `meta.links.next` | string | URL da próxima página. Retorna `null` na última página. |
| `meta.links.last` | string | URL da última página. |

Toda resposta inclui o cabeçalho `X-Request-Id`. Informe esse valor ao entrar em contato com o time de suporte da Segura™ sobre uma requisição específica.

---

## Erros

A API v2 retorna um `code` estruturado no corpo da resposta, junto a uma `message` legível. A coluna Mensagem da tabela a seguir apresenta esse código.

| Código HTTP | Mensagem | Causa possível | Solução |
| --- | --- | --- | --- |
| `401` | `api.auth.token.invalid` | O token de acesso está ausente, expirado ou inválido. | Solicite um novo token de acesso e reenvie a requisição. |
| `403` | `api.permission.denied` | A autorização não tem permissão de leitura nos recursos do PAM Core. | Peça ao administrador para verificar as permissões da autorização no A2A. |
| `422` | `api.fields.invalid` | O parâmetro `fields` nomeia um campo que não existe neste recurso ou nomeia um valor secreto. | Remova o campo do parâmetro `fields`. Valores secretos nunca estão disponíveis neste endpoint. |
| `429` | `rate_limit_exceeded` | A requisição excedeu o limite definido para o tenant, a aplicação ou o endpoint. | Reduza a frequência das requisições e tente novamente. |
| `500` | `api.internal.error` | Erro interno do servidor. | Entre em contato com o time de suporte da Segura™. |

A especificação e o critério de aceite AC-01 exigem `403` com `api.fields.sensitive.not.allowed`. A build 4.2.13 retorna `422` com `api.fields.invalid` e a mensagem "Field 'secret.private_key' is not valid for this resource." Esta tabela registra o comportamento observado.

Para as mensagens de erro de autenticação e a política de `403` versus `404`, consulte [API v2 - Conventions and shared behaviors](/v4-2/docs/api-v2-conventions-and-shared-behaviors).

---

## Documentos relacionados

- [API v2 - Conventions and shared behaviors](/v4-2/docs/api-v2-conventions-and-shared-behaviors)
- [GET | Listar uma chave SSH por [id]](/v4-2/docs/api-v2-get-list-an-ssh-key)
- [Como gerenciar autorizações no A2A](/v4-2/docs/api-v2-how-to-manage-authorizations-in-a2a)
- [Sobre aplicações e autorizações no A2A](/v4-2/docs/a2a-about-applications-and-authorizations)