--- title: "GET | Listar uma chave SSH por [id]" slug: "api-v2-get-list-an-ssh-key" updated: 2026-11-03T14:47:51Z published: 2026-11-03T14:47:51Z canonical: "docs.senhasegura.io/api-v2-get-list-an-ssh-key" --- > ## 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 uma chave SSH por [id] ## Descrição Acesse o registro completo de uma chave SSH no PAM Core, utilizando o modelo canônico da API v2. A resposta retorna a estrutura `SSHKeyV2` completa, incluindo os dispositivos associados, as configurações de sessão e as configurações de renovação da chave. Uma chave SSH inativa retorna `200` com `ssh_key.active` definido como `false`. Ela não é tratada como inexistente. --- ## 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). - Um token de acesso OAuth 2.0 válido. Para mais informações, acesse [Como autenticar uma aplicação A2A](/v4-2/docs/how-to-authenticate-an-application-in-a2a). --- ## Requisição `GET` `/api/v2/pam/ssh-keys/{id}` ### Parâmetros de caminho | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `id` | string | Sim | Código único de identificação da chave SSH, atribuído pela Segura™. | ### Parâmetros de query | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `fields` | array[string] | Não | Retorna apenas os campos indicados. Aceita qualquer campo do modelo canônico, em notação de ponto. Solicitar um campo inexistente, ou um valor secreto, é rejeitado. | #### Campos sensíveis: nunca retornados `ssh_key.private_key` e `ssh_key.password` são classificados como secretos. Eles nunca são incluídos na resposta e não podem ser solicitados por meio de `fields`. A resposta informa apenas se cada um está configurado, por meio de `secret.has_private_key` e `secret.has_password`. Attention Não há como ler uma chave privada ou senha armazenada por este endpoint. A forma controlada e auditada de obter um valor secreto é a ação de checkout, que não está disponível nesta versão. --- ### Exemplos de requisição `GET` `{{url}}/api/v2/pam/ssh-keys/2267` Com projeção de campos: `GET` `{{url}}/api/v2/pam/ssh-keys/2267?fields=ssh_key.key_name,ssh_key.active,secret.has_private_key` --- ## Resposta ``` HTTP/1.1 200 OK ``` ### Exemplo de corpo da resposta: canônico completo ``` { "data": { "id": "2267", "ssh_key": { "key_name": "key_segura", "username": "key_segura", "active": true, "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI...", "ssh_key_algorithm": "rsa", "credential_tags": ["prod", "ci-cd"], "ssh_key_owner": { "name": "John Doe" }, "last_used_at": "2026-08-29T12:34:56Z", "device_tags": ["prod", "database"] }, "secret": { "has_private_key": true, "has_password": false, "type": "ssh-key" }, "main_device": { "id": "159", "hostname": "dev", "management_ip": "10.10.10.6" }, "devices": [ { "id": "159", "hostname": "dev", "product": "Oracle Linux VM", "device_type": "Server", "site": "SP-DC1", "domain_name": "CORP" } ], "session": { "use_own_credential": false, "authentication_credential": { "id": "88", "username": "auth-user" }, "authentication_device": { "id": "159", "hostname": "dev" }, "automation_macros": [ { "id": "5", "name": "ERP Access", "connectivity": "SSH" } ], "restrict_remote_app_only": true }, "key_renewal": { "automatic_change_enabled": true, "set_password_on_renewal": true, "use_key_itself_to_connect": false, "authentication_credential": { "id": "90", "username": "renew-user" } } }, "meta": { "links": { "self": "/api/v2/pam/ssh-keys/2267" }, "actions": { "activate": "/api/v2/pam/ssh-keys/2267/activate", "deactivate": "/api/v2/pam/ssh-keys/2267/deactivate", "rotate": "/api/v2/pam/ssh-keys/2267/rotate" } } } ``` A especificação lista cinco ações, mas o checkout não está disponível nesta versão e a situação do check-in não está resolvida. Confirme quais chaves a build realmente retorna. ### Exemplo de corpo da resposta: com projeção de campos ``` { "data": { "id": "2267", "ssh_key": { "key_name": "key_segura", "active": true }, "secret": { "has_private_key": true } }, "meta": { "links": { "self": "/api/v2/pam/ssh-keys/2267?fields=ssh_key.key_name,ssh_key.active,secret.has_private_key" } } } ``` A projeção preserva a estrutura aninhada. Os campos solicitados são retornados em sua posição canônica, e não de forma plana. --- ## Campos do corpo da resposta | Campo | Tipo | Descrição | | --- | --- | --- | | `data.id` | string | Código único de identificação da chave SSH, atribuído pela Segura™. | | `data.ssh_key` | object | Atributos principais da chave SSH. | | `data.ssh_key.key_name` | string | Nome que identifica a chave SSH. | | `data.ssh_key.username` | string | Nome de usuário associado à chave SSH. | | `data.ssh_key.active` | boolean | Indica se a chave SSH está ativa. | | `data.ssh_key.public_key` | string | Conteúdo da chave pública. Retorna `null` quando não há chave pública configurada. | | `data.ssh_key.ssh_key_algorithm` | string | Algoritmo do par de chaves. | | `data.ssh_key.credential_tags` | array[string] | Tags associadas à chave SSH. Retorna um array vazio quando não há tags configuradas. | | `data.ssh_key.ssh_key_owner` | object | Responsável associado à chave SSH. Retorna `null` quando não há responsável configurado. | | `data.ssh_key.ssh_key_owner.name` | string | Nome do responsável. | | `data.ssh_key.last_used_at` | string | Data e hora do último uso registrado, no formato ISO 8601. Retorna `null` quando a chave não tem uso registrado. | | `data.ssh_key.device_tags` | array[string] | Tags derivadas dos dispositivos vinculados. Somente leitura. | | `data.secret` | object | Indicadores do segredo armazenado. Valores secretos nunca são retornados. | | `data.secret.has_private_key` | boolean | Indica se há uma chave privada configurada. | | `data.secret.has_password` | boolean | Indica se há uma senha configurada. | | `data.secret.type` | string | Tipo do segredo. Sempre `ssh-key` neste recurso. | | `data.main_device` | object | Dispositivo principal associado à chave SSH. A rotação é executada nesse dispositivo. | | `data.main_device.id` | string | Código único de identificação do dispositivo principal. | | `data.main_device.hostname` | string | Hostname do dispositivo principal. | | `data.main_device.management_ip` | string | Endereço IP usado para gerenciar o dispositivo principal. | | `data.devices` | array de objetos | Dispositivos adicionais vinculados à chave SSH. | | `data.devices[].id` | string | Código único de identificação do dispositivo. | | `data.devices[].hostname` | string | Hostname do dispositivo. | | `data.devices[].product` | string | Produto executado no dispositivo. Exemplo: `Oracle Linux VM`. | | `data.devices[].device_type` | string | Tipo do dispositivo. Exemplo: `Server`. | | `data.devices[].site` | string | Site ao qual o dispositivo pertence. | | `data.devices[].domain_name` | string | Domínio associado ao dispositivo. Retorna `null` quando o dispositivo não está vinculado a um domínio. | | `data.session` | object | Configurações de sessão aplicadas quando a chave é usada para acesso remoto. | | `data.session.use_own_credential` | boolean | Indica se a sessão se autentica com a própria chave. | | `data.session.authentication_credential` | object | Credencial usada para autenticar a sessão. Retornada quando `use_own_credential` é `false`. | | `data.session.authentication_device` | object | Dispositivo usado para autenticar a sessão. Retornado quando `use_own_credential` é `false`. | | `data.session.automation_macros` | array de objetos | Macros de automação associadas à sessão. Retorna um array vazio quando não há nenhuma configurada. | | `data.session.automation_macros[].connectivity` | string | Protocolo de conectividade da macro. Exemplo: `SSH`. | | `data.session.restrict_remote_app_only` | boolean | Indica se a chave está restrita ao acesso por aplicação remota. | | `data.key_renewal` | object | Configurações de renovação aplicadas pela ação de rotação. | | `data.key_renewal.automatic_change_enabled` | boolean | Indica se a renovação automática da chave está habilitada. | | `data.key_renewal.set_password_on_renewal` | boolean | Indica se uma senha é definida quando a chave é renovada. | | `data.key_renewal.use_key_itself_to_connect` | boolean | Indica se a renovação conecta usando a própria chave. | | `data.key_renewal.authentication_credential` | object | Credencial usada para conectar durante a renovação. Retornada quando `use_key_itself_to_connect` é `false`. | | `meta.links.self` | string | URL da requisição atual, incluindo a query string enviada. | | `meta.actions` | object | Endpoints de ação disponíveis para esta chave SSH, filtrados pelas permissões da autorização. | Info O bloco `session` deste recurso não corresponde ao bloco `session` retornado pelos endpoints de credenciais. Os dois contratos divergem nesta versão. Consulte as descrições de campo deste documento em vez de presumir paridade. 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. | 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. | | `404` | `api.resource.not_found` | A chave SSH não existe ou está fora do escopo da autorização. | Verifique o código de identificação enviado no caminho. | | `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`. | | `429` | `rate_limit_exceeded` | O limite de requisições foi excedido. | 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™. | ### Exemplo de resposta de erro `422` um valor secreto foi solicitado por meio de `fields`: ``` { "code": "api.fields.invalid", "message": "Field 'secret.private_key' is not valid for this resource.", "details": null } ``` 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 o `422` apresentado. Este documento registra o comportamento observado. Para as mensagens de erro de autenticação e a política de `403` versus `404`, acesse [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 todas as chaves SSH](/v4-2/docs/api-v2-get-list-all-ssh-keys) - [POST | Rotacionar chave SSH](/v4-2/docs/api-v2-post-rotate-ssh-key) - [Como gerenciar autorizações no A2A](/v4-2/docs/api-v2-how-to-manage-authorizations-in-a2a)