1. Docs
  2. API Reference
  3. Preview replacing a role's permissions

Preview replacing a role's permissions

POST/api/v1/roles/{id}/permissions/preview

Reports 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

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

idstring 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

Only the people gaining access, or only those losing it

one of "gains" · "loses"

permissionstring Optional

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

max length 200

Request body

application/json

permission_keysstring[] Required

Responses

application/json

  • dataRolePermissionsPreviewDto*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

Returned object

Request
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"
    ]
  }'
Response
{
  "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
  }
}
Related endpoints
GETList roles
POSTCreate a custom role
GETGet a role
PATCHUpdate a role
DELETEDelete a role
GETGet permissions for a role
PUTReplace permissions on a role
Was this page helpful?

Tell us how we can improve this guide.