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 browse a static version of the Cerbos OpenAPI specification on this site. To interactively explore the API, launch a Cerbos instance and access 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.52.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
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)
  "actions":  ["approve", "view"], (3)
  "resource":  {
    "policyVersion": "dev", (4)
    "kind":  "leave_request", (5)
    "scope": "acme.corp", (6)
    "attr":  { (7)
      "owner":  "alicia"
    }
  },
  "principal":  {
    "id":  "alicia", (8)
    "policyVersion": "dev", (9)
    "scope": "acme.corp", (10)
    "roles":  ["user"], (11)
    "attr": { (12)
      "geography": "GB"
    }
  },
  "includeMeta": true, (13)
  "auxData": { (14)
    "jwt": {
      "token": "xxx.yyy.zzz", (15)
      "keySetId": "ks-1" (16)
    }
  }
}

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 perform 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

Example: request.resource.attr.status == "PENDING_APPROVAL"

{
  "expression": {
    "operator": "eq",
    "operands": [
      {
        "variable": "request.resource.attr.status"
      },
      {
        "value": "PENDING_APPROVAL"
      }
    ]
  }
}

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

Cerbos API Examples

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