Get where an identity holds each permission
/api/v1/identities/{id}/grantsReturns, for the current Environment, one page of (permission, node_id) rows: every permission the identity holds, paired with each hierarchy node its grants were made at — the nodes themselves, not expanded through their descendants. Rows are ordered by permission, then node; a caller building the whole map walks every page. A grant already means "this node and everything beneath it", so a caller answers a node-scoped question by walking up from the node in question and looking for one of these roots, using a copy of the parent edges fetched once from GET /api/v1/nodes/parents and shared across identities. Answers both scopes without a further call: the permission appearing at all is the Application-wide answer, and the walk is the node-scoped one. By default, assignments outside their effective window are excluded. With include=windows, every assignment is a row carrying effective_from and effective_to (null for an unbounded side), in effect or not, so a caller applies the window itself: it can say why a check fails (the grant has ended, or has not begun) and drop a grant at its boundary without reading again. Returns 404 when the identity has no membership in this Environment.
Authentication
Authorization Option A JWT access token. Never send alongside X-API-Key: a request carrying both is refused.
X-API-Key Option B API key for management-tier access. Never send alongside an Authorization header: a request carrying both is refused.
Path Parameters
idstring Required Query Parameters
pagenumber Optional Page number (1-based)
takenumber Optional Items per page (1-100, default 20)
includeenum Optional `windows` adds `effective_from` and `effective_to` to every row and includes assignments outside their window, so the caller applies the window itself.
Responses
application/json
model_version *integerThe version of the authorization model these rows describe. A client that evaluates from them refuses a version it does not know rather than guessing.
items *IdentityGrantResponseDto[]pagination *PageMetaDto
application/json
error *ApiErrorBodyDto
application/json
error *ApiErrorBodyDto
application/json
error *ApiErrorBodyDto
application/json
error *ApiErrorBodyDto
Pagination
This endpoint returns a paginated collection. Use the query parameters below to page through results.
pagenumberPage number (1-indexed). Defaults to 1.
takenumberItems 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
curl -X GET "https://auth.canopy-io.com/api/v1/identities/value/grants?page=0&take=0&include=windows" \ -H "X-API-Key: $CANOPY_API_KEY"
{ "model_version": 0, "items": [ { "permission": "reports.view", "node_id": "00000000-0000-0000-0000-000000000000", "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 } }
Tell us how we can improve this guide.