The Cerbos API

This documentation is for a previous version of Cerbos. Choose 0.40.0 from the version picker at the top right or navigate to https://docs.cerbos.dev for the latest version.

The main API endpoint for making policy decisions is the /api/check/resources REST endpoint (cerbos.svc.v1.CerbosService/CheckResources RPC in the gRPC API). You can view the latest API documentation from a running Cerbos instance by accessing the root directory of the HTTP endpoint using a browser.

docker run --rm --name cerbos -p 3592:3592 -p 3593:3593 ghcr.io/cerbos/cerbos:0.32.0

Navigate to http://localhost:3592/ using your browser to explore the Cerbos API documentation.

Alternatively, you can explore the API using the following methods as well:

Client SDKs

Other languages coming soon

Demos

Get help

Request and response formats

CheckResources (/api/check/resources)

This is the main API entrypoint for checking permissions for a set of resources.

Request
{
  "requestId": "test", (1)
  "principal": {
    "id": "alice", (2)
    "policyVersion": "20210210", (3)
    "scope": "acme.corp", (4)
    "roles": [ (5)
      "employee"
    ],
    "attr": { (6)
      "department": "accounting",
      "geography": "GB",
      "team": "design"
    }
  },
  "resources": [ (7)
    {
      "resource": {
        "id": "XX125", (8)
        "kind": "leave_request", (9)
        "policyVersion": "20210210", (10)
        "scope": "acme.corp", (11)
        "attr": { (12)
          "department": "accounting",
          "geography": "GB",
          "id": "XX125",
          "owner": "john",
          "team": "design"
        }
      },
      "actions": [ (13)
        "view:public",
        "approve",
        "create"
      ]
    }
  ],
  "auxData": { (14)
    "jwt": {
        "token": "xxx.yyy.zzz", (15)
        "keySetId": "ks1" (16)
    }
  },
  "includeMeta": true (17)
}
1 Request ID is an optional, application-provided identifier useful for correlating logs.
2 ID of the principal whose permissions are being checked. This usually comes from the identity provider (IdP).
3 Principal policy version. Optional. The server falls back to the configured default version if this is not specified.
4 Principal policy scope. Optional. See Scoped Policies.
5 The roles attached to this principal by the identity provider.
6 Free-form context data about this principal. Policy rule conditions are evaluated based on these values.
7 List of resources the principal is attempting to access. Up to 50 resources may be provided in a single request by default. This limit can be configured.
8 ID of the resource.
9 Resource kind. This is used to determine the resource policy that applies to this resource.
10 Resource policy version. Optional. The server falls back to the configured default version if this is not specified.
11 Resource policy scope. Optional. See Scoped Policies.
12 Free-form context data about this resource. Policy rule conditions are evaluated based on these values.
13 List of actions being performed on the resource. Up to 50 actions per resource may be provided by default. This limit can be configured.
14 Optional section for providing auxiliary data.
15 JWT to use as an auxiliary data source.
16 ID of the keyset to use to verify the JWT. Optional if only a single keyset is configured.
17 Optional flag to receive metadata about request evaluation.
Response
{
  "requestId": "test", (1)
  "results": [ (2)
    {
      "resource": { (3)
        "id": "XX125",
        "kind": "leave_request",
        "policyVersion": "20210210",
        "scope": "acme.corp"
      },
      "actions": { (4)
        "view:public": "EFFECT_ALLOW",
        "approve": "EFFECT_DENY"
      },
      "outputs": [ (5)
        {
          "src": "resource.leave_request.v20210210/acme#rule-001", (6)
          "val": "create_allowed:john" (7)
        },
        {
          "src": "resource.leave_request.v20210210#public-view",
          "val": {
            "id": "john",
            "keys": ["foo", "bar", "baz"]
          }
        }
      ],
      "validationErrors": [ (8)
        {
          "path": "/department",
          "message": "value must be one of \"marketing\", \"engineering\"",
          "source": "SOURCE_PRINCIPAL"
        },
        {
          "path": "/department",
          "message": "value must be one of \"marketing\", \"engineering\"",
          "source": "SOURCE_RESOURCE"
        }
      ],
      "meta": { (9)
        "actions": {
          "view:public": {
            "matchedPolicy": "resource.leave_request.v20210210/acme.corp", (10)
            "matchedScope": "acme" (11)
          },
          "approve": {
            "matchedPolicy": "resource.leave_request.v20210210/acme.corp"
          }
        },
        "effectiveDerivedRoles": [ (12)
          "employee_that_owns_the_record",
          "any_employee"
        ]
      }
    }
  ]
}
1 Request ID that was sent with the request.
2 List of results. Items are in the same order as they were sent in the request.
3 Resource identifiers.
4 Access decisions for each of the actions.
5 List of outputs from policy evaluation, if there are any. See Outputs.
6 Name of the rule that produced the output.
7 Output value produced by the rule.
8 Validation errors, if schema enforcement is enabled and the request didn’t conform to the schema.
9 Metadata (if includeMeta was true in the request)
10 Name of the policy that produced the decision for this action.
11 Name of the scope that was active when the decision was made for the action.
12 List of derived roles that were activated.

CheckResourceSet (/api/check)

Deprecated since Cerbos 0.16.0. Use CheckResources instead.

Checks permissions for a set of homogeneous resources.

Request and Response
Request
{
  "requestId":  "test01", (1)
  "actions":  ["view"], (2)
  "resource":  {
    "policyVersion": "dev", (3)
    "kind":  "album:object", (4)
    "scope": "acme.corp", (5)
    "instances": { (6)
      "XX125": { (7)
        "attr":  { (8)
          "owner":  "alicia",
          "id":  "XX125",
          "public": false,
          "tags": ["x", "y"],
          "flagged": false
        }
      }
    }
  },
  "principal":  {
    "id":  "alicia", (9)
    "policyVersion": "dev", (10)
    "scope": "acme.corp", (11)
    "roles":  ["user"], (12)
    "attr": { (13)
      "geography": "GB"
    }
  },
  "includeMeta": true, (14)
  "auxData": { (15)
    "jwt": {
        "token": "xxx.yyy.zzz", (16)
        "keySetId": "ks1" (17)
    }
  }
}
1 Request ID can be anything that uniquely identifies a request.
2 Actions being performed on the resource instances. Required. Up to 10 actions may be provided in a single request.
3 Resource policy version. Optional. The server falls back to the configured default version if this is not specified.
4 Resource kind. Required. This value is used to determine the resource policy to evaluate.
5 Resource scope. Optional. See Scoped Policies.
6 Container for the set of resource instances to check. You can check access to multiple resource instances in a single request by adding them under this field.
7 A unique identifier for a resource instance. This identifier will be used in the response to indicate the result of the policy evaluation.
8 Free-form context data about this resource instance. Policy rule conditions are evaluated based on these values.
9 ID of the principal performing the actions. Required.
10 Principal policy version. Optional. The server falls back to the configured default version if this is not specified.
11 Principal scope. Optional. See Scoped Policies.
12 Static roles that are assigned to this principal by your identity management system. Required.
13 Free-form context data about this principal. Policy rule conditions are evaluated based on these values.
14 An optional flag to signal that the response should include metadata about policy evaluation. Useful for debugging.
15 Optional section for providing auxiliary data.
16 JWT to use as an auxiliary data source.
17 ID of the keyset to use to verify the JWT. Optional if only a single keyset is configured.
Response
{
  "requestId": "test01", (1)
  "resourceInstances": {
    "XX125": { (2)
      "actions": {
        "view": "EFFECT_ALLOW" (3)
      },
      "validationErrors": [ (4)
        {
          "path": "/department",
          "message": "value must be one of \"marketing\", \"engineering\"",
          "source": "SOURCE_PRINCIPAL"
        }
      ]
    }
  },
  "meta": { (5)
    "resourceInstances": {
      "XX125": {
        "actions": {
          "view": {
            "matchedPolicy": "album:object:default", (6)
            "matchedScope": "acme.corp" (7)
          }
        },
        "effectiveDerivedRoles": [ (8)
          "owner"
        ]
      }
    }
  }
}
1 The request ID received from the request. Helpful for correlating logs.
2 Unique ID of the resource.
3 Policy decision for each action on the resource.
4 Optional validation errors if schema enforcement is enabled.
5 Optional metadata about request evaluation.
6 The policy that matched to make the decision for the given action.
7 The policy scope that was active when the decision was made.
8 Derived roles that were activated.

CheckResourceBatch (/api/check_resource_batch)

Deprecated since Cerbos 0.16.0. Use CheckResources instead.

Unlike CheckResourceSet — which checks access to resource instances of the same kind, CheckResourceBatch allows checking access to multiple heterogeneous resource instances.

Request and Response
Request
{
  "requestId": "test",
  "principal": {
    "id": "donald_duck",
    "policyVersion": "20210210",
    "scope": "acme.corp",
    "roles": [
      "employee"
    ],
    "attr": {
      "department": "marketing",
      "geography": "GB",
      "team": "design"
    }
  },
  "resources": [
    {
      "actions": [
        "view:public",
        "approve",
        "create"
      ],
      "resource": {
        "kind": "leave_request",
        "policyVersion": "20210210",
        "scope": "acme.corp",
        "id": "XX125",
        "attr": {
          "department": "marketing",
          "geography": "GB",
          "id": "XX125",
          "owner": "john",
          "team": "design"
        }
      }
    },
    {
      "actions": [
        "view:public",
        "approve",
        "create"
      ],
      "resource": {
        "kind": "leave_request",
        "policyVersion": "20210210",
        "id": "XX150",
        "attr": {
          "department": "marketing",
          "geography": "GB",
          "id": "XX125",
          "owner": "mary",
          "team": "design"
        }
      }
    }
  ],
  "auxData": {
    "jwt": {
        "token": "xxx.yyy.zzz",
        "keySetId": "ks1"
    }
  }
}
Response
{
  "requestId":  "test",
  "results":  [
    {
      "resourceId":  "XX125",
      "actions":  {
        "approve":  "EFFECT_DENY",
        "create":  "EFFECT_DENY",
        "view:public":  "EFFECT_ALLOW"
      },
      "validationErrors": [
        {
          "path": "/department",
          "message": "value must be one of \"marketing\", \"engineering\"",
          "source": "SOURCE_RESOURCE"
        }
      ]
    },
    {
      "resourceId":  "XX150",
      "actions":  {
        "approve":  "EFFECT_DENY",
        "create":  "EFFECT_DENY",
        "view:public":  "EFFECT_ALLOW"
      }
    }
  ]
}

PlanResources (/api/plan/resources)

Produces a query plan that can be used to obtain a list of resources that a principal is allowed to perform a particular action on.

Request
{
  "requestId":  "test01", (1)
  "action":  "approve", (2)
  "resource":  {
    "policyVersion": "dev", (3)
    "kind":  "leave_request", (4)
    "scope": "acme.corp", (5)
    "attr":  { (6)
      "owner":  "alicia"
    }
  },
  "principal":  {
    "id":  "alicia", (7)
    "policyVersion": "dev", (8)
    "scope": "acme.corp", (9)
    "roles":  ["user"], (10)
    "attr": { (11)
      "geography": "GB"
    }
  },
  "includeMeta": true, (12)
  "auxData": { (13)
    "jwt": {
      "token": "xxx.yyy.zzz", (14)
      "keySetId": "ks-1" (15)
    }
  }
}
1 Request ID can be anything that uniquely identifies a request.
2 Action being performed on the resource instances. Required.
3 Resource policy version. Optional. The server falls back to the configured default version if this is not specified.
4 Resource kind. Required. This value is used to determine the resource policy to evaluate.
5 Resource scope. Optional. See Scoped Policies.
6 Free-form context data about the resources under consideration. The object holds all attributes known about the resource at the time the request. Optional. Policy rule conditions will be (partially) evaluated based on these values. If an effective policy rule condition(s) requires a resource attribute not present in this object, then the response will contain the condition(s) abstract syntax tree.
7 ID of the principal performing the actions. Required.
8 Principal policy version. Optional. The server falls back to the configured default version if this is not specified.
9 Principal scope. Optional. See Scoped Policies.
10 Static roles that are assigned to this principal by your identity management system. Required.
11 Free-form context data about this principal. Policy rule conditions are evaluated based on these values.
12 An optional flag to signal that the response should include metadata about evaluation. Useful for debugging.
13 Optional section for providing auxiliary data.
14 JWT to use as an auxiliary data source.
15 ID of the keyset to use to verify the JWT. Optional if only a single keyset is configured.
Response
{
  "requestId": "test01",
  "action": "approve",
  "resourceKind": "leave_request",
  "policyVersion": "dev",
  "filter": {
    "kind": "KIND_CONDITIONAL", (1)
    "condition": { (2)
        "expression":  {
          "operator":  "eq",
          "operands":  [
            { "variable":  "request.resource.attr.status" },
            { "value":  "PENDING_APPROVAL" }
          ]
        }
    }
  },
  "meta": {
    "filterDebug": "(request.resource.attr.status == \"PENDING_APPROVAL\")" (3)
  },
}
1 Filter kind can be KIND_ALWAYS_ALLOWED, KIND_ALWAYS_DENIED or KIND_CONDITIONAL. See below for description of what these values mean.
2 Populated only if kind ` is `KIND_CONDITIONAL. Contains the abstract syntax tree (AST) of the condition that must be satisfied to allow the action.
3 Condition AST represented as a human readable string. Useful for debugging.

Structure of the filter block

The kind field defines the filter kind.

KIND_ALWAYS_ALLOWED

The principal is unconditionally allowed to perform the action

KIND_ALWAYS_DENIED

The principal is unconditionally not permitted to perfrom the action

KIND_CONDITIONAL

The principal is allowed to perform the action if the condition is satisfied

The condition field holds the AST of the condition that must be satisfied. It is rooted in an expression that has an operator (e.g. equals, greater than) and operands (e.g. a constant value, a variable or another expression).

Common Operators
Operator Description

add

Addition (+)

and

Logical AND (&&)

div

Division (/)

eq

Equality (==)

ge

Greater than or equal (>=)

gt

Greater than (>)

in

List membership (in)

index

Array or map index

lambda

Anonymous function

le

Less than or equal (⇐)

list

List constructor

lt

Less than (<)

mod

Modulo (%)

mult

Multiplication (*)

ne

Not equal (!=)

not

Logical NOT

or

Logical OR

sub

Subtract (-)
Example: request.resource.attr.status == "PENDING_APPROVAL"
{
  "expression": {
    "operator": "eq",
    "operands": [
      {
        "variable": "request.resource.attr.status"
      },
      {
        "value": "PENDING_APPROVAL"
      }
    ]
  }
}
Example: (request.resource.attr.department == "marketing") && (request.resource.attr.team != "design")
{
  "expression": {
    "operator": "and",
    "operands": [
      {
        "expression": {
          "operator": "eq",
          "operands": [
            {
              "variable": "request.resource.attr.department"
            },
            {
              "value": "marketing"
            }
          ]
        }
      },
      {
        "expression": {
          "operator": "ne",
          "operands": [
            {
              "variable": "request.resource.attr.team"
            },
            {
              "value": "design"
            }
          ]
        }
      }
    ]
  }
}
Example: request.resource.attr.values.filter(t, t > 0)
{
  "expression": {
    "operator": "filter",
    "operands": [
      {
        "variable": "request.resource.attr.values"
      },
      {
        "expression": {
          "operator": "lambda",
          "operands": [
            {
              "variable": "t"
            },
            {
              "expression": {
                "operator": "gt",
                "operands": [
                  {
                    "variable": "t"
                  },
                  {
                    "value": 0
                  }
                ]
              }
            }
          ]
        }
      }
    ]
  }
}

ServerInfo (/api/server_info)

Returns Cerbos server version.

Response
{
  "version": "0.25.0",
  "commit": "6b5a051a160398a3c04370f742e6090fab2ed0b8",
  "buildDate": "2023-02-13T09:31:48Z"
}

Accessing the API

Using curl to access the REST API

cat <<EOF | curl --silent "localhost:3592/api/check/resources?pretty" -d @-
{
  "requestId": "test",
  "principal": {
    "id": "alice",
    "roles": ["employee"],
    "attr": {
      "department": "accounting",
      "geography": "GB",
      "team": "design"
    }
  },
  "resources": [
    {
      "resource": {
        "id": "XX125",
        "kind": "leave_request",
        "attr": {
          "department": "accounting",
          "geography": "GB",
          "id": "XX125",
          "owner": "john",
          "team": "design"
        }
      },
      "actions": [
        "view:public",
        "approve",
        "create"
      ]
    }
  ]
}
EOF

Using grpcurl to access the gRPC API

cat <<EOF | grpcurl -plaintext -d @ localhost:3593 cerbos.svc.v1.CerbosService/CheckResources
{
  "requestId": "test",
  "principal": {
    "id": "alice",
    "roles": ["employee"],
    "attr": {
      "department": "accounting",
      "geography": "GB",
      "team": "design"
    }
  },
  "resources": [
    {
      "resource": {
        "id": "XX125",
        "kind": "leave_request",
        "attr": {
          "department": "accounting",
          "geography": "GB",
          "id": "XX125",
          "owner": "john",
          "team": "design"
        }
      },
      "actions": [
        "view:public",
        "approve",
        "create"
      ]
    }
  ]
}
EOF

Generating API clients

The Cerbos OpenAPI specification can be obtained from a running Cerbos instance by accessing http://localhost:3592/schema/swagger.json. Cerbos gRPC API definitions are published to the Buf schema registry (BSR) and can be easily added to your project if you use the Buf build system for protobufs.

REST

There are many tools available to generate clients from an OpenAPI specification. https://openapi.tools/#sdk is a good resource for finding a tool suitable for your preferred language.

Example: Generating a Java client using OpenAPI Generator

OpenAPI Generator has support for many popular programming languages and frameworks. Please consult the documentation to find the client generation instructions for your favourite language.

This is an example of using the popular OpenAPI Generator service to generate a Java client API.

  • Download the Cerbos OpenAPI specification

    curl -Lo swagger.json http://localhost:3592/schema/swagger.json

  • Run the OpenAPI Generator

    docker run --rm -v $(pwd):/oas openapitools/openapi-generator-cli generate -i /oas/swagger.json -g java -o /oas/java

gRPC

Any language

You can access the Cerbos protobuf definitions from the Cerbos source tree. However, the easiest way to generate client code for your preferred language is to use the Buf build tool to obtain the published API definitions from the Buf schema registry (BSR).

  • Run buf export buf.build/cerbos/cerbos-api -o proto to download the API definitions with dependencies to the proto directory.

  • You can now use buf generate or protoc to generate code using the protobufs available in the proto directory.

  • If you don’t want to download protobufs and then to generate code using buf or protoc, you can use the Cerbos grpc-tools container to generate code for languages like Java, NodeJS, Python, C# etc.

Go

The Cerbos Go SDK uses the gRPC API to communicate with Cerbos. The generated gRPC and protobuf code is available under the github.com/cerbos/cerbos/api/genpb package.

go get github.com/cerbos/cerbos/api

You can also make use of the remote generation feature of Buf schema registry to pull down the Cerbos gRPC API as a Go module:

go get go.buf.build/cerbos/gen-go/cerbos/cerbos-api