The Cerbos API

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

• Go

• Java

• JavaScript

• .NET

• Laravel

• PHP

• Python

• Ruby

• Rust

Other languages coming soon

Demos

• Application (Python)

• GraphQL Service (NodeJS)

• REST Service (Go)

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

ServerInfo (/api/server_info)

Returns Cerbos server version.

Response

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

Access Evaluation

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

AuthZEN API Examples

Metadata endpoint:

curl --silent "localhost:3592/.well-known/authzen-configuration?pretty"

Access Evaluation (single):

cat <<EOF | curl --silent "localhost:3592/access/v1/evaluation?pretty" -d @-
{
  "subject": {
    "type": "user",
    "id": "alice",
    "properties": {
      "cerbos.roles": ["employee"],
      "department": "accounting",
      "geography": "GB",
      "team": "design"
    }
  },
  "resource": {
    "type": "leave_request",
    "id": "XX125",
    "properties": {
      "department": "accounting",
      "geography": "GB",
      "owner": "john",
      "team": "design"
    }
  },
  "action": {
    "name": "view:public",
    "properties": {}
  },
  "context": {
    "cerbos.requestId": "test",
    "cerbos.includeMeta": true
  }
}
EOF

Access Evaluations (batch):

cat <<EOF | curl --silent "localhost:3592/access/v1/evaluations?pretty" -d @-
{
  "subject": {
    "type": "user",
    "id": "alice",
    "properties": {
      "cerbos.roles": ["employee"],
      "department": "accounting",
      "geography": "GB",
      "team": "design"
    }
  },
  "resource": {
    "type": "leave_request",
    "id": "XX125",
    "properties": {
      "department": "accounting",
      "geography": "GB",
      "owner": "john",
      "team": "design"
    }
  },
  "context": {
    "cerbos.requestId": "test",
    "cerbos.includeMeta": true
  },
  "evaluations": [\
    {\
      "action": {\
        "name": "view:public",\
        "properties": {}\
      }\
    },\
    {\
      "action": {\
        "name": "approve",\
        "properties": {}\
      }\
    },\
    {\
      "action": {\
        "name": "create",\
        "properties": {}\
      }\
    }\
  ]
}
EOF