1. Docs
  2. API Reference
  3. Preview a deny

Preview a deny

POST/api/v1/denies/preview

Who a deny would take access from, without creating it. Takes the body POST /denies takes. losing_count counts every active person and machine client the target names who holds one of the permissions today on the node's lineage or beneath it, and permissions counts them per key; kept_count the ones an exception role spares; already_refused_count the ones another deny already refuses there. items is one page (page, take) of those losing access, each with the keys it loses, named only to a reader who may see the Environment's people (people_named; machine clients are always named), and kept up to 20 exception holders with the role that spares them. Read-only. Requires deny.manage.

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.

Query Parameters

pagenumber Optional

Page number (1-based)

min 1

takenumber Optional

Items per page (1-100, default 20)

range 1–100

Request body

application/json

target_typeenum Required

What the deny targets: one identity, one machine client (`oauth_client`), or every holder of a role, wherever they hold it.

one of "identity" · "oauth_client" · "role"

target_idstring · uuid Required

The identity, the machine client's row id, or the role it targets.

permission_keysstring[] Required

The permission keys it refuses, each in the Environment's catalog.

node_idstring · uuid Required

The node it applies at. It refuses there and at every node beneath, and no grant lower down can undo it.

exception_role_idsstring[] Optional

Roles whose holders keep access despite the deny, wherever they hold them, while that assignment is in effect. Use one so the people who manage access are not locked out.

reasonstring Required

Why the deny exists. Required: it is the record an auditor reads.

max length 500

Responses

application/json

  • dataDenyPreviewResponseDto*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

Returned object

DenyPreviewResponseDtoView all properties on this resource
Request
curl -X POST "https://auth.canopy-io.com/api/v1/denies/preview?page=0&take=0" \
  -H "X-API-Key: $CANOPY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target_type": "identity",
    "target_id": "00000000-0000-0000-0000-000000000000",
    "permission_keys": [
      "documents.view"
    ],
    "node_id": "00000000-0000-0000-0000-000000000000",
    "exception_role_ids": [
      "string"
    ],
    "reason": "Office A files are under legal hold."
  }'
Response
{
  "data": {
    "people_named": false,
    "losing_count": 0,
    "kept_count": 0,
    "already_refused_count": 0,
    "permissions": [
      {
        "permission": "documents.view",
        "losing": 0
      }
    ],
    "people": {
      "items": [
        {
          "type": "identity",
          "id": "00000000-0000-0000-0000-000000000000",
          "name": "string",
          "email": "string",
          "loses": [
            "string"
          ]
        }
      ],
      "pagination": {
        "page": 0,
        "take": 0,
        "item_count": 0,
        "page_count": 0,
        "has_previous_page": false,
        "has_next_page": false
      }
    },
    "kept": [
      {
        "type": "identity",
        "id": "00000000-0000-0000-0000-000000000000",
        "name": "string",
        "email": "string",
        "exception_role": {
          "id": "00000000-0000-0000-0000-000000000000",
          "name": "string"
        }
      }
    ]
  }
}
 Related endpoints
GETList denies
POSTCreate a deny
GETGet a deny
DELETEDelete a deny
GETWhat a deny refuses today
 Was this page helpful?

Tell us how we can improve this guide.

Canopy