CheckResources API

Check a principal’s permissions to a batch of heterogeneous resources and actions

The CheckResources API is the primary authorization endpoint for checking whether a principal has permission to perform specific actions on resources. It supports checking multiple resources and actions in a single request.

Endpoint

gRPC

rpc CheckResources(CheckResourcesRequest) returns (CheckResourcesResponse)

Request Parameters

requestId · string

Optional application-specific ID useful for correlating logs for analysis.

Example: "c2db17b8-4f9f-4fb1-acfd-9162a02be42b"

includeMeta · boolean

Add request processing metadata to the response. When true, the response includes information about which policies matched and which derived roles were effective.

principal · object · required

A person or application attempting to perform the actions on the set of resources.

Show Principal fields

id · string · required

ID of the principal.

Example: "alicia"

roles · string[] · required

Roles assigned to this principal from your identity management system. Must contain at least one role.

Example: ["user"]

attr · object

Key-value pairs of contextual data about this principal that should be used during policy evaluation.

Example: {"beta_tester": true}

policyVersion · string

The policy version to use to evaluate this request. If not specified, will default to the server-configured default version.

Example: "default"

scope · string

A dot-separated scope that describes the hierarchy this principal belongs to. This is used for determining policy inheritance.

Example: "acme.corp"

resources · object[] · required

List of resources and actions to check. Must contain at least one resource.

Show Resource entry fields

actions · string[] · required

List of actions being performed on the resource. Must contain at least one action and all actions must be unique.

Example: ["view", "delete"]

resource · object · required

The resource to check permissions for.

Show Resource fields

kind · string · required

Name of the resource kind being accessed.

Example: "album:object"

id · string · required

ID of the resource instance.

Example: "XX125"

attr · object

Key-value pairs of contextual data about this resource that should be used during policy evaluation.

Example: {"owner": "alicia", "public": false}

policyVersion · string

The policy version to use to evaluate this request. If not specified, will default to the server-configured default version.

Example: "default"

scope · string

A dot-separated scope that describes the hierarchy this resource belongs to. This is used for determining policy inheritance.

Example: "acme.corp"

auxData · object

Structured auxiliary data useful for evaluating the request.

Show AuxData fields

jwt · object

JWT from the original request.

Show JWT fields

token · string · required

JWT from the original request.

keySetId · string

Key ID to use when decoding the token (defined in the Cerbos server configuration).

Response Fields

requestId · string

Request ID provided in the request.

Example: "c2db17b8-4f9f-4fb1-acfd-9162a02be42b"

results · object[]

Result for each resource.

Show Result entry fields

resource · object

Information about the resource that was checked.

Show Resource fields

id · string

ID of the resource instance.

Example: "XX125"

kind · string

Name of the resource kind being accessed.

Example: "album:object"

policyVersion · string

The policy version used to evaluate this request.

Example: "default"

scope · string

The scope that was used for this resource.

actions · object

Mapping of each action to an effect. Each key is an action name, and the value is either EFFECT_ALLOW or EFFECT_DENY.

Example: {"view": "EFFECT_ALLOW", "delete": "EFFECT_DENY"}

validationErrors · object[]

List of validation errors (if schema validation is enabled).

meta · object

Metadata about policy evaluation (only included if includeMeta was set to true in the request).

Show Meta fields

actions · object

Metadata about the effect calculated for each action on this resource instance.

Show Effect metadata

matchedPolicy · string

Policy that matched to produce this effect.

Example: "resource.album_object.vdefault"

matchedScope · string

Policy scope that matched to produce this effect.

Example: "acme.corp.base"

effectiveDerivedRoles · string[]

Derived roles that were effective during policy evaluation.

Example: ["owner"]

outputs · object[]

Output for each rule with outputs configured.

Show Output entry fields

src · string

Rule that matched to produce this output.

Example: "resource.expense.v1/acme#rule-001"

val · any

Dynamic output, determined by user defined rule output.

cerbosCallId · string

Audit log call ID associated with this request.

Example

cURL

cat <<EOF | curl --silent "http://localhost:3592/api/check/resources?pretty" -d @-
{
  "requestId": "test01",
  "includeMeta": true,
  "principal": {
    "id": "alicia",
    "roles": [
      "user"
    ]
  },
  "resources": [
    {
      "actions": [
        "view"
      ],
      "resource": {
        "id": "XX125",
        "kind": "album:object",
        "attr": {
          "owner": "alicia",
          "public": false,
          "flagged": false
        }
      }
    }
  ]
}
EOF

Use Cases

Single Resource Check

The most common use case is checking if a user can perform actions on a single resource:

{
  "principal": {
    "id": "user123",
    "roles": ["user"]
  },
  "resources": [
    {
      "actions": ["view", "edit", "delete"],
      "resource": {
        "kind": "document",
        "id": "doc456",
        "attr": {
          "owner": "user123"
        }
      }
    }
  ]
}

Batch Resource Check

You can check permissions for multiple heterogeneous resources in a single request:

{
  "principal": {
    "id": "user123",
    "roles": ["user"]
  },
  "resources": [
    {
      "actions": ["view"],
      "resource": {
        "kind": "document",
        "id": "doc456"
      }
    },
    {
      "actions": ["approve"],
      "resource": {
        "kind": "expense",
        "id": "exp789"
      }
    }
  ]
}

With Metadata

Request metadata to understand which policies matched:

{
  "includeMeta": true,
  "principal": {
    "id": "user123",
    "roles": ["user"]
  },
  "resources": [
    {
      "actions": ["view"],
      "resource": {
        "kind": "document",
        "id": "doc456"
      }
    }
  ]
}