1. Docs
  2. API Reference
  3. List the people a stored access preview reaches

List the people a stored access preview reaches

GET/api/v1/access-previews/{previewId}/people

One page of the people a stored access preview reaches, by name, one row per person: for a move or a permissions preview the keys gained and lost with via, the grants behind them; for a delete preview via, their assignments that go. The preview is the one its id names, made by POST …/move/preview, …/delete/preview or …/permissions/preview; it is read only by the principal that made it, in the Environment it was made in, and only until its expires_at, so anyone else's, an expired one and an unknown id all answer 404. Each read resolves the change again, under the gate its creation passed, and answers 409 version_mismatch once the node, its destination or the role has changed since the preview: preview the change again. The query narrows the page and never the preview's counts: q (name or email), direction (gains or loses) and permission (one key) on a change preview, role_id on a delete preview, page and take (up to 5000). A reader who may not see the Environment's people (people_named false on the preview) gets an empty page, whatever the query.

Authentication

Bearer TokenAuthorization Option A

JWT access token. Never send alongside X-API-Key: a request carrying both is refused.

API KeyX-API-Key Option B

API key for management-tier access. Never send alongside an Authorization header: a request carrying both is refused.

Path Parameters

previewIdstring Required

Query Parameters

pagenumber Optional

Page of people (1-based)

min 1

takenumber Optional

People per page (1-5000, default 20)

range 1–5000

qstring Optional

Only people whose name or email contains this, ignoring case

max length 200

directionenum Optional

Change previews: only the people gaining access, or only those losing it

one of "gains" · "loses"

permissionstring Optional

Change previews: only the people gaining or losing this permission key (with `direction`, only that side)

max length 200

role_idstring · uuid Optional

Delete previews: only the people holding this role in the subtree

Responses

application/json

  • itemsPreviewPersonDto[]*
  • paginationPageMetaDto*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

Pagination

This endpoint returns a paginated collection. Use the query parameters below to page through results.

pagenumber

Page number (1-indexed). Defaults to 1.

takenumber

Items per page (1 to 100). Defaults to 20.

Each response includes an items array alongside a pagination object with item_count, page_count, has_previous_page, and has_next_page fields.

Returned object

PreviewPersonDtoView all properties on this resource
Request
curl -X GET "https://auth.canopy-io.com/api/v1/access-previews/value/people?page=0&take=0&q=value&direction=gains&permission=value&role_id=value" \
  -H "X-API-Key: $CANOPY_API_KEY"
Response
{
  "items": [
    {
      "identity": {
        "id": "string",
        "first_name": "string",
        "last_name": "string",
        "name": "string",
        "email": "string",
        "avatar_url": "string"
      },
      "gained": [
        "string"
      ],
      "lost": [
        "string"
      ],
      "via": [
        {
          "role": {
            "id": "string",
            "name": "string"
          },
          "node": {
            "id": "string",
            "name": "string"
          }
        }
      ]
    }
  ],
  "pagination": {
    "page": 0,
    "take": 0,
    "item_count": 0,
    "page_count": 0,
    "has_previous_page": false,
    "has_next_page": false
  }
}
 Related endpoints
GETExport the people a stored access preview reaches
 Was this page helpful?

Tell us how we can improve this guide.

Canopy