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 view the latest API documentation from a running Cerbos instance by accessing 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.32.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
Other languages coming soon
Demos
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"
]
}
}
]
}
CheckResourceSet (/api/check)
| Deprecated since Cerbos 0.16.0. Use CheckResources instead. |
Checks permissions for a set of homogeneous resources.
Request
{
"requestId": "test01",
"actions": ["view"],
"resource": {
"policyVersion": "dev",
"kind": "album:object",
"scope": "acme.corp",
"instances": {
"XX125": {
"attr": {
"owner": "alicia",
"id": "XX125",
"public": false,
"tags": ["x", "y"],
"flagged": false
}
}
}
},
"principal": {
"id": "alicia",
"policyVersion": "dev",
"scope": "acme.corp",
"roles": ["user"],
"attr": {
"geography": "GB"
}
},
"includeMeta": true,
"auxData": {
"jwt": {
"token": "xxx.yyy.zzz",
"keySetId": "ks1"
}
}
}
Response
{
"requestId": "test01",
"resourceInstances": {
"XX125": {
"actions": {
"view": "EFFECT_ALLOW"
},
"validationErrors": [
{
"path": "/department",
"message": "value must be one of \"marketing\", \"engineering\"",
"source": "SOURCE_PRINCIPAL"
}
]
}
},
"meta": {
"resourceInstances": {
"XX125": {
"actions": {
"view": {
"matchedPolicy": "album:object:default",
"matchedScope": "acme.corp"
}
},
"effectiveDerivedRoles": [
"owner"
]
}
}
}
}
CheckResourceBatch (/api/check_resource_batch)
| Deprecated since Cerbos 0.16.0. Use CheckResources instead. |
Unlike CheckResourceSet — which checks access to resource instances of the same kind, CheckResourceBatch allows checking access to multiple heterogeneous resource instances.
Request and Response
Request
{
"requestId": "test",
"principal": {
"id": "donald_duck",
"policyVersion": "20210210",
"scope": "acme.corp",
"roles": ["employee"],
"attr": {
"department": "marketing",
"geography": "GB",
"team": "design"
}
},
"resources": [
{
"actions": [
"view:public",
"approve",
"create"
],
"resource": {
"kind": "leave_request",
"policyVersion": "20210210",
"scope": "acme.corp",
"id": "XX125",
"attr": {
"department": "marketing",
"geography": "GB",
"id": "XX125",
"owner": "john",
"team": "design"
}
}
},
{
"actions": [
"view:public",
"approve",
"create"
],
"resource": {
"kind": "leave_request",
"policyVersion": "20210210",
"id": "XX150",
"attr": {
"department": "marketing",
"geography": "GB",
"id": "XX125",
"owner": "mary",
"team": "design"
}
}
}
],
"auxData": {
"jwt": {
"token": "xxx.yyy.zzz",
"keySetId": "ks1"
}
}
}
Response
{
"requestId": "test",
"results": [
{
"resourceId": "XX125",
"actions": {
"approve": "EFFECT_DENY",
"create": "EFFECT_DENY",
"view:public": "EFFECT_ALLOW"
},
"validationErrors": [
{
"path": "/department",
"message": "value must be one of \"marketing\", \"engineering\"",
"source": "SOURCE_RESOURCE"
}
]
},
{
"resourceId": "XX150",
"actions": {
"approve": "EFFECT_DENY",
"create": "EFFECT_DENY",
"view:public": "EFFECT_ALLOW"
}
}
]
}
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\")"
}
}
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