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 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.40.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
| Demos are constantly being added or updated by the Cerbos team. Visit https://github.com/orgs/cerbos/repositories?language=&q=demo&sort=&type=all for the latest list. |
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)
"resource": {
"policyVersion": "dev", (3)
"kind": "leave_request", (4)
"scope": "acme.corp", (5)
"attr": { (6)
"owner": "alicia"
}
},
"principal": {
"id": "alicia", (7)
"policyVersion": "dev", (8)
"scope": "acme.corp", (9)
"roles": ["user"], (10)
"attr": { (11)
"geography": "GB"
}
},
"includeMeta": true, (12)
"auxData": { (13)
"jwt": {
"token": "xxx.yyy.zzz", (14)
"keySetId": "ks-1" (15)
}
}
}
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"
}
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
Generating API clients
The Cerbos OpenAPI specification can be obtained from a running Cerbos instance by accessing http://localhost:3592/schema/swagger.json. Cerbos gRPC API definitions are published to the Buf schema registry (BSR) and can be easily added to your project if you use the Buf build system for protobufs.