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.46.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", 
  "principal": {
    "id": "alice", 
    "policyVersion": "20210210", 
    "scope": "acme.corp", 
    "roles": [ 
      "employee"
    ],
    "attr": { 
      "department": "accounting",
      "geography": "GB",
      "team": "design"
    }
  },
  "resources": [ 
    {
      "resource": {
        "id": "XX125", 
        "kind": "leave_request", 
        "policyVersion": "20210210", 
        "scope": "acme.corp", 
        "attr": { 
          "department": "accounting",
          "geography": "GB",
          "id": "XX125",
          "owner": "john",
          "team": "design"
        }
      },
      "actions": [ 
        "view:public",
        "approve",
        "create"
      ]
    }
  ],
  "auxData": { 
    "jwt": {
        "token": "xxx.yyy.zzz", 
        "keySetId": "ks1" 
    }
  },
  "includeMeta": true 
}

Response

{
  "requestId": "test", 
  "results": [ 
    {
      "resource": { 
        "id": "XX125",
        "kind": "leave_request",
        "policyVersion": "20210210",
        "scope": "acme.corp"
      },
      "actions": { 
        "view:public": "EFFECT_ALLOW",
        "approve": "EFFECT_DENY"
      },
      "outputs": [ 
        {
          "src": "resource.leave_request.v20210210/acme#rule-001", 
          "val": "create_allowed:john" 
        },
        {
          "src": "resource.leave_request.v20210210#public-view",
          "val": {
            "id": "john",
            "keys": ["foo", "bar", "baz"]
          }
        }
      ],
      "validationErrors": [ 
        {
          "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": { 
        "actions": {
          "view:public": {
            "matchedPolicy": "resource.leave_request.v20210210/acme.corp", 
            "matchedScope": "acme" 
          },
          "approve": {
            "matchedPolicy": "resource.leave_request.v20210210/acme.corp"
          }
        },
        "effectiveDerivedRoles": [ 
          "employee_that_owns_the_record",
          "any_employee"
        ]
      }
    }
  ],
  "cerbosCallId": "01HHENANTHFD5DV3HZGDKB87PJ" 
}

PlanResources (/api/plan/resources)

Generates a query plan for checking permissions.

Request

{
  "requestId":  "test01", 
  "action":  "approve", 
  "actions":  ["approve", "view"], 
  "resource":  {
    "policyVersion": "dev", 
    "kind":  "leave_request", 
    "scope": "acme.corp", 
    "attr":  { 
      "owner":  "alicia"
    }
  },
  "principal":  {
    "id":  "alicia", 
    "policyVersion": "dev", 
    "scope": "acme.corp", 
    "roles":  ["user"], 
    "attr": { 
      "geography": "GB"
    }
  },
  "includeMeta": true, 
  "auxData": { 
    "jwt": {
      "token": "xxx.yyy.zzz", 
      "keySetId": "ks-1" 
    }
  }
}

Response

{
  "requestId": "test01",
  "action": "approve",
  "resourceKind": "leave_request",
  "policyVersion": "dev",
  "filter": {
    "kind": "KIND_CONDITIONAL", 
    "condition": { 
        "expression":  {
          "operator":  "eq",
          "operands":  [
            { "variable":  "request.resource.attr.status" },
            { "value":  "PENDING_APPROVAL" }
          ]
        }
    }
  },
  "meta": {
    "filterDebug": "(request.resource.attr.status == \"PENDING_APPROVAL\")" 
  },
  "cerbosCallId": "01HHENANTHFD5DV3HZGDKB87PJ" 
}

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