---
title: "GET | List an SSH key by [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 | List an SSH key by [id]

## Description

Access the complete record of one SSH key in PAM Core, using the API v2 canonical model. The response returns the full `SSHKeyV2` structure, including the associated devices, the session settings, and the key renewal settings.

An inactive SSH key returns `200` with `ssh_key.active` set to `false`. It is not treated as missing.

---

## 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).
- A valid OAuth 2.0 access token. For more information, access [How to authenticate an application in A2A](/v4-2/docs/how-to-authenticate-an-application-in-a2a).

---

## Request

`GET` `/api/v2/pam/ssh-keys/{id}`

### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Unique identification code of the SSH key, assigned by Segura™. |

### Query parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `fields` | array[string] | No | Returns only the named fields. Accepts any field of the canonical model, in dot notation. Requesting a field that does not exist, or a secret value, is rejected. |

#### Sensitive fields: never returned

`ssh_key.private_key` and `ssh_key.password` are classified as secret. They are never included in the response, and they cannot be requested through `fields`. The response reports only whether each one is configured, through `secret.has_private_key` and `secret.has_password`.

              Attention

              

There is no way to read a stored private key or passphrase through this endpoint. The controlled, audited way to obtain a secret value is the checkout action, which is not available in this version.

---

### Example requests

`GET` `{{url}}/api/v2/pam/ssh-keys/2267`

With field projection:

`GET` `{{url}}/api/v2/pam/ssh-keys/2267?fields=ssh_key.key_name,ssh_key.active,secret.has_private_key`

---

## Response

```
HTTP/1.1 200 OK
```

### Example response body: full canonical

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

The specification lists five actions, but checkout does not ship in this version and the status of checkin is unresolved. Confirm which keys the build actually returns.

### Example response body: with field projection

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

Projection preserves the nested structure. Requested fields are returned in their canonical position, not flattened.

---

## Response body fields

| Field | Type | Description |
| --- | --- | --- |
| `data.id` | string | Unique identification code of the SSH key, assigned by Segura™. |
| `data.ssh_key` | object | Core SSH key attributes. |
| `data.ssh_key.key_name` | string | Name that identifies the SSH key. |
| `data.ssh_key.username` | string | Username associated with the SSH key. |
| `data.ssh_key.active` | boolean | Indicates whether the SSH key is active. |
| `data.ssh_key.public_key` | string | Public key content. Returns `null` when no public key is configured. |
| `data.ssh_key.ssh_key_algorithm` | string | Algorithm of the key pair. |
| `data.ssh_key.credential_tags` | array[string] | Tags associated with the SSH key. Returns an empty array when no tags are configured. |
| `data.ssh_key.ssh_key_owner` | object | Owner associated with the SSH key. Returns `null` when no owner is configured. |
| `data.ssh_key.ssh_key_owner.name` | string | Name of the owner. |
| `data.ssh_key.last_used_at` | string | Date and time of the last recorded use, in ISO 8601 format. Returns `null` when the key has no recorded use. |
| `data.ssh_key.device_tags` | array[string] | Tags derived from the linked devices. Read-only. |
| `data.secret` | object | Indicators for the stored secret. Secret values are never returned. |
| `data.secret.has_private_key` | boolean | Indicates whether a private key is configured. |
| `data.secret.has_password` | boolean | Indicates whether a passphrase is configured. |
| `data.secret.type` | string | Secret type. Always `ssh-key` for this resource. |
| `data.main_device` | object | Main device associated with the SSH key. A rotation runs against this device. |
| `data.main_device.id` | string | Unique identification code of the main device. |
| `data.main_device.hostname` | string | Hostname of the main device. |
| `data.main_device.management_ip` | string | IP address used to manage the main device. |
| `data.devices` | array of objects | Additional devices linked to the SSH key. |
| `data.devices[].id` | string | Unique identification code of the device. |
| `data.devices[].hostname` | string | Hostname of the device. |
| `data.devices[].product` | string | Product running on the device. Example: `Oracle Linux VM`. |
| `data.devices[].device_type` | string | Type of the device. Example: `Server`. |
| `data.devices[].site` | string | Site the device belongs to. |
| `data.devices[].domain_name` | string | Domain associated with the device. Returns `null` when the device is not linked to a domain. |
| `data.session` | object | Session settings applied when the key is used for remote access. |
| `data.session.use_own_credential` | boolean | Indicates whether the session authenticates with the key itself. |
| `data.session.authentication_credential` | object | Credential used to authenticate the session. Returned when `use_own_credential` is `false`. |
| `data.session.authentication_device` | object | Device used to authenticate the session. Returned when `use_own_credential` is `false`. |
| `data.session.automation_macros` | array of objects | Automation macros associated with the session. Returns an empty array when none are configured. |
| `data.session.automation_macros[].connectivity` | string | Connectivity protocol of the macro. Example: `SSH`. |
| `data.session.restrict_remote_app_only` | boolean | Indicates whether the key is restricted to remote application access. |
| `data.key_renewal` | object | Key renewal settings applied by the rotate action. |
| `data.key_renewal.automatic_change_enabled` | boolean | Indicates whether automatic key renewal is enabled. |
| `data.key_renewal.set_password_on_renewal` | boolean | Indicates whether a passphrase is set when the key is renewed. |
| `data.key_renewal.use_key_itself_to_connect` | boolean | Indicates whether the renewal connects using the key itself. |
| `data.key_renewal.authentication_credential` | object | Credential used to connect during renewal. Returned when `use_key_itself_to_connect` is `false`. |
| `meta.links.self` | string | URL of the current request, including the query string sent. |
| `meta.actions` | object | Action endpoints available for this SSH key, filtered by the permissions of the authorization. |

              Info

              

The `session` block of this resource does not match the `session` block returned by the credentials endpoints. The two contracts diverge in this version. Read the field descriptions in this document rather than assuming parity.

Every response includes the `X-Request-Id` header. Provide this value when you contact the Segura™ support team about a specific request.

---

## Errors

API v2 returns a structured `code` in the response body, alongside a human-readable `message`.

| HTTP code | Message | Possible cause | Solution |
| --- | --- | --- | --- |
| `401` | `api.auth.token.invalid` | The access token is missing, expired, or invalid. | Request a new access token and resend the request. |
| `403` | `api.permission.denied` | The authorization does not have read permission to PAM Core resources. | Ask the administrator to check the authorization permissions in A2A. |
| `404` | `api.resource.not_found` | The SSH key does not exist, or it is outside the scope of the authorization. | Check the identification code sent in the path. |
| `422` | `api.fields.invalid` | The `fields` parameter names a field that does not exist on this resource, or names a secret value. | Remove the field from the `fields` parameter. |
| `429` | `rate_limit_exceeded` | The request rate limit was exceeded. | Reduce the request rate and try again. |
| `500` | `api.internal.error` | Internal server error. | Contact the Segura™ support team. |

### Example error response

`422` a secret value was requested through `fields`:

```
{
    "code": "api.fields.invalid",
    "message": "Field 'secret.private_key' is not valid for this resource.",
    "details": null
}
```

The specification and acceptance criterion AC-01 both require `403` with `api.fields.sensitive.not.allowed`. The 4.2.13 build returns the `422` shown. This document records the observed behavior.

For authentication error messages and the `403` versus `404` policy, access [API v2 - Conventions and shared behaviors](/v4-2/docs/api-v2-conventions-and-shared-behaviors).

---

## Related documents

- [API v2 - Conventions and shared behaviors](/v4-2/docs/api-v2-conventions-and-shared-behaviors)
- [GET | List all SSH keys](/v4-2/docs/api-v2-get-list-all-ssh-keys)
- [POST | Rotate SSH key](/v4-2/docs/api-v2-post-rotate-ssh-key)
- [How to manage authorizations in A2A](/v4-2/docs/api-v2-how-to-manage-authorizations-in-a2a)