GET | List all SSH keys

Description

List all SSH keys associated with your authorization in PAM Core, using the API v2 canonical model. The endpoint returns a paginated projection of the SSHKeyV2 entity and supports filtering, sorting, and field projection.

Secret values are never returned. The response reports only whether a private key or a password is configured, through the secret.has_private_key and secret.has_password indicators.

Info

The v1 equivalent remains available and is documented in SSH keys. Field names differ between the two versions: v1 enabled is v2 ssh_key.active, v1 tags is v2 ssh_key.credential_tags, and the v1 identifier is replaced by the Segura®-assigned id.

Prerequisites

Authorization with read permission to PAM Core, granted by the administrator in A2A. For more information, access How to manage authorizations in A2A.

Request

GET /api/v2/pam/ssh-keys

Query parameters

Filter names use dot notation that mirrors the response structure. Only main_device_id is flat, because it references another entity by ID.

Filters

Field	Type	Description
`ssh_key.key_name`	string	Filters by key name. Exact match.
`ssh_key.username`	string	Filters by the username associated with the key. Exact match.
`ssh_key.active`	boolean	Filters by active status. Accepted values: `true`, `false`.
`ssh_key.credential_tags`	array[string]	Filters by one or more tags. Use comma-separated values for OR logic; repeat the parameter for AND logic.
`main_device_id`	integer	Filters by the ID of the main device associated with the key.
`secret.has_private_key`	boolean	Filters by whether a private key is configured. Accepted values: `true`, `false`.
`secret.has_password`	boolean	Filters by whether a passphrase is configured. Accepted values: `true`, `false`.

The specification states this filter is mandatory. The engineering refinement of 2026-07-15 questioned that decision and it was never closed. Every other filter is optional.

Requesting a secret value through field projection is rejected. See the Errors section.

Sorting

sort_by accepts one or more response fields and validates them against an allowed list. Invalid fields are rejected. For the parameter format, direction syntax, and multi-field precedence, see API v2 - Conventions and shared behaviors.

Pagination

Field	Type	Description
`page`	integer	Page number. Default: `1`.
`limit`	integer	Results per page. Default: `50`. Maximum: `200`.

Example request

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

Response

HTTP/1.1 200 OK

Example response body

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

The list projection is flat. Each item carries the fields directly, not inside the ssh_key and secret objects the detail endpoint returns. Filter names still use dot notation, so secret.has_private_key filters on the field this response returns as has_private_key.

Response body fields

Field	Type	Description
`data`	array of objects	List of SSH keys matching the request filters.
`data[].id`	string	Unique identification code of the SSH key, assigned by Segura®.
`data[].key_name`	string	Name that identifies the SSH key.
`data[].username`	string	Username associated with the SSH key.
`data[].active`	boolean	Indicates whether the SSH key is active.
`data[].main_device`	object	Main device associated with the SSH key. This is the device where a rotation runs.
`data[].main_device.id`	string	Unique identification code of the main device.
`data[].main_device.hostname`	string	Hostname of the main device.
`data[].credential_tags`	array[string]	Tags associated with the SSH key. Returns an empty array when no tags are configured.
`data[].has_private_key`	boolean	Indicates whether a private key is configured for this SSH key. Secret values are never returned.
`data[].has_password`	boolean	Indicates whether a passphrase is configured for this SSH key. Secret values are never returned.
`data[].last_used_at`	string	Date and time of the last recorded use, in ISO 8601 format. Example: `2026-01-29T12:34:56Z`. Returns `null` when the key has no recorded use.
`meta`	object	Pagination metadata and navigation links.
`meta.pagination`	object	Pagination details for the current result set.
`meta.pagination.page`	integer	Current page number.
`meta.pagination.limit`	integer	Maximum number of results per page.
`meta.pagination.total_items`	integer	Total number of SSH keys matching the filters.
`meta.pagination.total_pages`	integer	Total number of pages.
`meta.links`	object	Navigation links for paginating through results.
`meta.links.self`	string	URL of the current page, including the query string sent in the request.
`meta.links.first`	string	URL of the first page.
`meta.links.next`	string	URL of the next page. Returns `null` on the last page.
`meta.links.last`	string	URL of the last page.

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. The Message column in the following table lists that code.

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.
`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. Secret values are never available on this endpoint.
`429`	`rate_limit_exceeded`	The request exceeded the rate limit for the tenant, application, or endpoint.	Reduce the request rate and retry.
`500`	`api.internal.error`	Internal server error.	Contact the Segura® support team.

The specification and acceptance criterion AC-01 both require 403 with api.fields.sensitive.not.allowed. The 4.2.13 build returns 422 with api.fields.invalid and the message "Field 'secret.private_key' is not valid for this resource." This table records the observed behavior.

For authentication error messages and the 403 versus 404 policy, see API v2 - Conventions and shared behaviors.