The Cerbos API

The main API endpoint for making policy decisions is the /api/check REST endpoint (cerbos.svc.v1.CerbosService/CheckResourceSet 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.7.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

Available

Go Java NodeJS

Coming soon

C# Python Ruby Rust

Demos

Get help

Request and response formats

CheckResourceSet (/api/check)

Request
{
  "requestId":  "test01", (1)
  "actions":  ["view"], (2)
  "resource":  {
    "policyVersion": "dev", (3)
    "kind":  "album:object", (4)
    "instances": { (5)
      "XX125": { (6)
        "attr":  { (7)
          "owner":  "alicia",
          "id":  "XX125",
          "public": false,
          "tags": ["x", "y"],
          "flagged": false
        }
      }
    }
  },
  "principal":  {
    "id":  "alicia", (8)
    "policyVersion": "dev", (9)
    "roles":  ["user"], (10)
    "attr": { (11)
      "geography": "GB"
    }
  },
  "includeMeta": true (12)
}
1 Request ID can be anything that uniquely identifies a request.
2 Actions 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 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.
6 A unique identifier for a resource instance. This identifier will be used in the response to indicate the result of the policy evaluation.
7 Free-form context data about this resource instance. Policy rule conditions are evaluated based on these values.
8 ID of the principal performing the actions. Required.
9 Principal policy version. Optional. The server falls back to the configured default version if this is not specified.
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 policy evaluation. Useful for debugging.
Response
{
  "requestId": "test01", (1)
  "resourceInstances": {
    "XX125": { (2)
      "actions": {
        "view": "EFFECT_ALLOW" (3)
      }
    }
  },
  "meta": { (4)
    "resourceInstances": {
      "XX125": {
        "actions": {
          "view": {
            "matchedPolicy": "album:object:default" (5)
          }
        },
        "effectiveDerivedRoles": [ (6)
          "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 metadata about request evaluation.
5 The policy that matched to make the decision for the given action.
6 Derived roles that were activated.

CheckResourceBatch (/api/check_resource_batch)

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

Request
{
  "requestId": "test",
  "principal": {
    "id": "donald_duck",
    "policyVersion": "20210210",
    "roles": [
      "employee"
    ],
    "attr": {
      "department": "marketing",
      "geography": "GB",
      "team": "design"
    }
  },
  "resources": [
    {
      "actions": [
        "view:public",
        "approve",
        "create"
      ],
      "resource": {
        "kind": "leave_request",
        "policyVersion": "20210210",
        "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"
        }
      }
    }
  ]
}
Response
{
  "requestId":  "test",
  "results":  [
    {
      "resourceId":  "XX125",
      "actions":  {
        "approve":  "EFFECT_DENY",
        "create":  "EFFECT_DENY",
        "view:public":  "EFFECT_ALLOW"
      }
    },
    {
      "resourceId":  "XX150",
      "actions":  {
        "approve":  "EFFECT_DENY",
        "create":  "EFFECT_DENY",
        "view:public":  "EFFECT_ALLOW"
      }
    }
  ]
}

Accessing the API

Using curl to access the REST API

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

Using grpcurl to access the gRPC API

cat <<EOF | grpcurl -plaintext -d @ localhost:3593 cerbos.svc.v1.CerbosService/CheckResourceSet
{
  "requestId":  "test01",
  "includeMeta": true,
  "actions":  ["view"],
  "resource":  {
    "policyVersion": "default",
    "kind":  "album:object",
    "instances": {
      "XX125": {
        "attr":  {
          "owner":  "alicia",
          "id":  "XX125",
          "public": false,
          "flagged": false
        }
      }
    }
  },
  "principal":  {
    "id":  "alicia",
    "policyVersion": "default",
    "roles":  ["user"]
  }
}

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

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 mod init and edit the generated buf.yaml file to add the following dependency declaration:

    version: v1
deps:
  - "buf.build/cerbos/cerbos-api"

  • Download the API definitions with dependencies to the proto directory.

    mkdir proto
buf mod update
buf export -o proto

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