PlanResources API

Produce a query plan with conditions that must be satisfied for accessing a set of instances of a resource

The PlanResources API generates a query plan that describes the conditions under which a principal can perform specific actions on a resource kind. This is particularly useful for implementing filtered list views where you need to show only the resources a user has access to.

Endpoint

gRPC

rpc PlanResources(PlanResourcesRequest) returns (PlanResourcesResponse)

Request Parameters

requestId · string

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

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

includeMeta · boolean

Opt to receive request processing metadata in the response.

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: "user123"

roles · string[] · required

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

Example: ["user", "manager"]

attr · object

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

Example: {"department": "engineering"}

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"

resource · object · required

The resource kind to generate the query plan for.

Show Resource fields

kind · string · required

Resource kind.

Example: "album:object"

attr · object

Key-value pairs of contextual data about the resource that are known at a time of the request.

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.

action · string

Deprecated: Use actions instead. Action to be applied to each resource in the list.

Example: "view"

actions · string[]

List of actions to generate the query plan for. Mutually exclusive with the singular action field. Must contain at least one action and all actions must be unique.

Example: ["view", "edit"]

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"

action · string

Deprecated: The action from the request.

actions · string[]

Actions from the request.

Example: ["view", "edit"]

resourceKind · string

Resource kind.

Example: "album:object"

policyVersion · string

The policy version.

Example: "default"

filter · object

Filter that describes the conditions for accessing resources.

Show Filter fields

kind · string

Filter kind. Defines whether the given action is always allowed, always denied or allowed conditionally.

Possible values:

• KIND_ALWAYS_ALLOWED: The principal always has access to all resources of this kind for the specified action(s)
• KIND_ALWAYS_DENIED: The principal never has access to any resources of this kind for the specified action(s)
• KIND_CONDITIONAL: Access depends on resource attributes matching the condition

condition · object

Filter condition. Only populated if kind is KIND_CONDITIONAL. This contains a query expression that can be translated into a database query using query plan adapters.

meta · object

Optional metadata about the request evaluation process.

Show Meta fields

filterDebug · string

Filter textual representation for debugging purposes.

matchedScopes · object

Matched policy scope for each action. Keys are action names, values are scope paths.

validationErrors · object[]

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

cerbosCallId · string

Audit log call ID associated with this request.

Example

cURL

cat <<EOF | curl --silent "http://localhost:3592/api/plan/resources?pretty" -d @-
{
  "requestId": "test02",
  "includeMeta": true,
  "principal": {
    "id": "alicia",
    "roles": ["user"],
    "attr": {
      "department": "marketing"
    }
  },
  "resource": {
    "kind": "album:object"
  },
  "action": "view"
}
EOF

Use Cases

Filtered List Views

The most common use case is implementing filtered list views where you need to show only the resources a user can access:

{
  "principal": {
    "id": "user123",
    "roles": ["user"]
  },
  "resource": {
    "kind": "document"
  },
  "action": "view"
}

The response can be used with query plan adapters to generate database queries:

• KIND_ALWAYS_ALLOWED: Return all documents
• KIND_ALWAYS_DENIED: Return no documents
• KIND_CONDITIONAL: Use the condition to filter the query (e.g., WHERE owner = 'user123')

Multiple Actions

Generate a query plan for multiple actions at once:

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

This returns a single filter that applies to all specified actions.

With Known Resource Attributes

If you have some resource attributes known at query time, include them to get more specific query plans:

{
  "principal": {
    "id": "user123",
    "roles": ["user"]
  },
  "resource": {
    "kind": "document",
    "attr": {
      "status": "published"
    }
  },
  "action": "view"
}

Query Plan Adapters

The filter returned by PlanResources can be converted to database-specific queries using query plan adapters:

• Prisma: Prisma Query Plan Adapter
• SQLAlchemy: SQLAlchemy Query Plan Adapter

These adapters automatically translate the filter conditions into the appropriate query format for your database.