The Cerbos API :: Cerbos Authorization Management Platform // Documentation

The Cerbos API


	This documentation is for a previous version of Cerbos. Choose 0.53.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.34.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:

Using an OpenAPI-compatible software like Postman or Insomnia to explore the Cerbos OpenAPI spec available at http://localhost:3592/schema/swagger.json.
Using grpcurl or any other tool that supports gRPC server reflection API to explore the gRPC API exposed on port 3593.

Client SDKs

Other languages coming soon

Demos


	Demos are constantly being added or updated by the Cerbos team. Visit https://github.com/orgs/cerbos/repositories?language=&q=demo&sort=&type=all for the latest list.

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)
}

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"\
        ]\
      }\
    }\
  ],
  "cerbosCallId": "01HHENANTHFD5DV3HZGDKB87PJ" (13)
}

`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)
    }
  }
}

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)
  },
  "cerbosCallId": "01HHENANTHFD5DV3HZGDKB87PJ" (4)
}

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).

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 (-)

Common Operators

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.

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

The Cerbos API

Client SDKs

Demos

Request and response formats

CheckResources (/api/check/resources)

PlanResources (/api/plan/resources)

Structure of the filter block

ServerInfo (/api/server_info)

Accessing the API

Using curl to access the REST API

Using grpcurl to access the gRPC API

Generating API clients

REST

Example: Generating a Java client using OpenAPI Generator

gRPC

`CheckResources` (`/api/check/resources`)

`PlanResources` (`/api/plan/resources`)

Structure of the `filter` block

`ServerInfo` (`/api/server_info`)