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

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",  
  "action":  "approve",  
  "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"
}