Preview replacing a role's permissions
/api/v1/roles/{id}/permissions/previewReports what replacing the role's permissions with permission_keys would change, without changing them: added and removed, and blockers, what would refuse the write, with the code and message it answers (organization.last_admin, rbac.roles_manage_below_organization); when any is listed no access is resolved. Otherwise, wherever the role is held now: holders, the identities it grants something to; identities_gaining, identities_losing and permissions, the counts per key, over everyone; and people, one page of the holders whose access changes, one row per person by name (a holder of the role at several nodes is one row), with the keys gained and lost once their other grants on each lineage are counted, via, the role at each node behind them, and pagination. The query narrows the page and never the counts: q (name or email), direction (gains or loses), permission (one key), page and take (up to 5000). People are named only for a reader who may see the Environment's people (people_named: env_identities.view in the Console, and production_identities.access in a production Environment; identity.view for an API key; access administration at the node for a tenant's administrator); anyone else gets the counts and an empty page, whatever the query. A disabled role (role_active: false) grants nothing either way. Resolved by the rules evaluate applies. Read-only. A key not in the Environment's catalog returns 404, as on the write. Send version as If-Match on the write. Requires the rbac.manage_roles permission.
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 of people (1-based)
takenumber Optional People per page (1-5000, default 20)
qstring Optional Only people whose name or email contains this, ignoring case
directionenum Optional Only the people gaining access, or only those losing it
permissionstring Optional Only the people gaining or losing this permission key (with `direction`, only that side)
Request body
application/json
permission_keysstring[] Required Responses
application/json
data *RolePermissionsPreviewDto
application/json
error *ApiErrorBodyDto
application/json
error *ApiErrorBodyDto
application/json
error *ApiErrorBodyDto
application/json
error *ApiErrorBodyDto
Returned object
curl -X POST "https://auth.canopy-io.com/api/v1/roles/value/permissions/preview?page=0&take=0&q=value&direction=gains&permission=value" \ -H "X-API-Key: $CANOPY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "permission_keys": [ "string" ] }'
{ "data": { "blockers": [ { "code": "hierarchy.reparent_cycle", "message": "string" } ], "people_named": false, "identities_gaining": 0, "identities_losing": 0, "permissions": [ { "permission": "string", "gaining": 0, "losing": 0 } ], "people": { "items": [ { "identity": { "id": "string", "first_name": "string", "last_name": "string", "name": "string", "email": "string", "avatar_url": "string" }, "gained": [ "string" ], "lost": [ "string" ], "via": [ { "role": {}, "node": {} } ] } ], "pagination": { "page": 0, "take": 0, "item_count": 0, "page_count": 0, "has_previous_page": false, "has_next_page": false } }, "role_id": "string", "version": 0, "role_active": false, "added": [ "string" ], "removed": [ "string" ], "holders": 0 } }
Tell us how we can improve this guide.