GET | List all devices

Description

List the devices associated with your authorization in PAM Core, using the v2 canonical model. Returns a paginated, filterable projection of the DeviceV2 entity.

Info

This endpoint belongs to the A2A API v2 surface and is available from Segura® version 4.2.9. Devices are served from the /api/v2/platform base path, not from /api/v2/pam like other v2 resources. The v1 equivalent is documented in GET | List all devices.

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/platform/devices

Query parameters

All query parameters are optional. When none are provided, the endpoint returns the first page of every device accessible to the authorization, using the list projection defined in the response schema.

Filters

Filters are combined with AND logic: a device must match every filter provided.

Field	Type	Description
`name`	string	Filters by device name. Exact match.
`address`	string	Filters by IP address, hostname, or management URL. Exact match.
`active`	boolean	Filters by operational state. Accepted values: `true`, `false`.
`type`	string	Filters by device type. Exact match on a registered type. See Device types.
`vendor`	string	Filters by vendor. Exact match on a registered vendor. See Device vendors.
`product`	string	Filters by product. Exact match on a registered product. See Device products.
`site`	string	Filters by site. Exact match on a registered site. See Device sites.
`domain_name`	string	Filters by domain name. Exact match. Omit this parameter to return devices regardless of domain association.
`tags`	array[string]	Filters by one or more tags. Use comma-separated values for OR logic (`tags=prod,database`); repeat the parameter for AND logic (`tags=prod&tags=database`).
`search`	string	Performs a free-text search across the device inventory.

Sorting

sort_by accepts one or more fields in the format field:asc or field:desc. Multiple fields are comma-separated and processed left to right. The default direction is asc. Example: sort_by=name:asc,type:desc.

Sortable fields: name, type, vendor, product, site.

An unsupported field returns 422 (api.sort.invalid_field) with a hint listing the allowed fields; an unsupported direction returns 422 (api.sort.invalid_direction). For full sorting rules, see API v2 — Conventions and shared behaviors.

Field projection

fields restricts the response to the listed fields, using namespaced paths. Example: fields=id,device.name,device.address.

data[].id is always returned, whether or not the projection requests it. A path that doesn't exist in the list projection returns 422 (api.fields.invalid).

Pagination

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

A limit above 200 returns 422 (api.pagination.limit.exceeded), and page=0 returns 422 (api.request.invalid_param). A page beyond the last one returns 200 with an empty data array and coherent pagination metadata.

Example request

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

Response

HTTP/1.1 200 OK

Every response carries an X-Request-Id header, which correlates the request across Segura® logs.

Example response body

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

Response body fields

Field	Type	Description
`data`	array of objects	List of devices matching the request filters. Returns an empty array when no device matches.
`data[].id`	string	Unique identification code of the device, assigned by Segura® in POST \| Create device. Always present in the response.
`data[].device`	object	Device attributes included in the list projection.
`data[].device.name`	string	Name that identifies the device.
`data[].device.address`	string	IP address, hostname, or management URL of the device.
`data[].device.active`	boolean	Indicates whether the device is active.
`data[].device.type`	string	Device type. Registered in Device types.
`data[].device.vendor`	string	Device vendor. Registered in Device vendors.
`data[].device.product`	string	Device product, bound to the vendor. Registered in Device products.
`data[].device.site`	string	Site where the device is located. Registered in Device sites.
`data[].device.domain_name`	string	Domain associated with the device. Returns `null` when the device isn't linked to a domain.
`data[].device.tags`	array[string]	Tags associated with the device. Returns an empty array when no tags are configured.
`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 devices 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.
`meta.links.first`	string	URL of the first page.
`meta.links.next`	string	URL of the next page.
`meta.links.last`	string	URL of the last page.

Info

The list projection is a subset of the canonical model. Fields such as criticality, owner, administrator_group, network_connector, enable_remote_app, connectivities, and session_settings are returned only by the detail endpoint. To retrieve them, access GET | List a device.

Errors

HTTP code	Message	Possible cause	Solution
`401`	`api.auth.token.invalid`	The access token is missing or has expired.	Request a new access token.
`403`	`api.permission.denied`	The authorization doesn't have read permission to PAM Core resources.	Ask the administrator to check the authorization permissions in A2A, then generate a new token.
`422`	`api.pagination.limit.exceeded`	`limit` is above the maximum of `200`.	Lower `limit` to `200` or less and paginate through the results.
`422`	`api.request.invalid_param`	`page` is `0` or otherwise out of range.	Send a `page` value of `1` or higher.
`422`	`api.sort.invalid_field`	`sort_by` references a field outside the sortable set.	Sort by `name`, `type`, `vendor`, `product`, or `site`.
`422`	`api.sort.invalid_direction`	`sort_by` uses a direction other than `asc` or `desc`.	Use `field:asc` or `field:desc`.
`422`	`api.fields.invalid`	`fields` references a path outside the list projection.	Check the field paths against the response schema.
`429`	`rate_limit_exceeded`	The rate limit for the tenant, application, or endpoint was exceeded.	Wait the number of seconds given in the `Retry-After` header, then retry.
`500`	`api.internal.error`	Internal server error.	Contact the Segura® support team.

Example error response

422 a requested projection field doesn't exist:

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

Authentication errors

Message	Possible cause	Solution
`Client authentication failed.`	Application authentication failure with the Segura® server.	Check the authentication parameters (`Access Token URL`, `Client ID`, and `Client secret`) and request a new access token.
`Invalid signature`	Failure in recognizing the client application URL.	Check the URL of the client application and resend the request.
`No route matched with those values.`	Missing authorization header in the API request.	Request a new access token.
`Request timed out.`	The request exceeded the timeout limit.	Check the connectivity between the source of the request and the Segura® server.

For the 403 versus 404 policy applied to resources outside your authorization scope, see API v2 — Conventions and shared behaviors.