1. Docs
  2. API Reference
  3. List who holds a permission at a node

List who holds a permission at a node

GET/api/v1/nodes/{id}/holders

Who holds permission at the node now, directly or by inheritance: one row per assignment on the node's lineage that grants it, with the identity, the role, the node it was granted at (granted_at), access_type (direct at the node itself) and the window. A person holding it through two roles appears twice. The rules are evaluate's: an active identity in the Environment, an enabled role carrying the key, the assignment's window open, and inside an organization an active membership there; every identity listed is one evaluate allows at the node. Supports filtering by q, role_id and access_type, sorting by name, role or access_type (name by default), and paging. Gated by hierarchy.view on the node and identity.view, since it names the Environment's people (an admin in a production Environment also needs production_identities.access). Returns 404 when the node is not found in this Environment.

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.

Production Environments require production_identities.accessDeveloper Console

Access identities in production Environments. Applies to users only, and only in an Environment marked production: its identities are real end users. API keys and identity principals are exempt.

Path Parameters

idstring Required

Query Parameters

pagenumber Optional

Page number (1-based)

min 1

takenumber Optional

Items per page (1-100, default 20)

range 1–100

qstring Optional

Search the holders by first name, last name or email.

max length 200

sort_byenum Optional

Sort column. Defaults to `name`, ascending. Ties end on the assignment id.

one of "name" · "role" · "access_type"

orderenum Optional

Sort direction

one of "asc" · "desc"

permissionstring Required

The permission to list holders of, by key.

max length 200

access_typeenum Optional

`direct` for grants made at the node itself, `inherited` for grants made above it.

one of "direct" · "inherited"

role_idstring Optional

Only grants through this role.

Responses

application/json

  • itemsNodeHolderDto[]*
  • paginationPageMetaDto*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

Errors

When the request can't be completed, the response body includes a stable error code you can branch on, and a correlation_id (also sent as the X-Correlation-Id header). Quote the correlation id when you contact support: it identifies the exact request in Canopy's logs. A request refused by an authorization check answers 403 with the code authorization.denied, and its data names the denial_reason and the permission checked.

403environment.production_identities_forbiddenForbidden
When it happens

The Environment is marked production and the caller is a user without production identity access.

Remediation

Manage these people in the Admin Workspace, or ask an administrator to grant the Production Support role, then retry.

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

NodeHolderDtoView all properties on this resource
Request
curl -X GET "https://auth.canopy-io.com/api/v1/nodes/value/holders?page=0&take=0&q=value&sort_by=name&order=asc&permission=value&access_type=direct&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"
      },
      "role": {
        "id": "string",
        "name": "string"
      },
      "assignment_id": "string",
      "granted_at": {
        "id": "string",
        "name": "string"
      },
      "access_type": "direct",
      "effective_from": "2026-04-20T12:00:00.000Z",
      "effective_to": "2026-04-20T12:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 0,
    "take": 0,
    "item_count": 0,
    "page_count": 0,
    "has_previous_page": false,
    "has_next_page": false
  }
}
 Related endpoints
GETList hierarchy nodes (scoped, paged)
POSTCreate a hierarchy node
GETList the hierarchy as parent edges
GETGet a hierarchy node
PATCHUpdate a hierarchy node
DELETEDelete a hierarchy node
GETGet subtree from a node
GETGet ancestor chain for a node
GETGet direct children of a node
POSTMove (reparent) a node
POSTPreview moving a node
POSTPreview deleting a node
GETList identities at a node
GETGet identity summary for a node
 Was this page helpful?

Tell us how we can improve this guide.

Canopy