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 PDP 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.54.0-prerelease

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",  
  "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"
}

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

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