API reference
Cerbos (latest)
Download OpenAPI specification:Download
Check Deprecated
[Deprecated: Use CheckResources API instead] Check whether a principal has permissions to perform the given actions on a set of resource instances.
Request Body schema: application/jsonrequired
PDP Request
requestId | string Optional application-specific ID useful for correlating logs for analysis. |
actions required | Array of strings non-empty unique List of actions being performed on the set of resources. |
required | object (enginev1Principal) A person or application attempting to perform the actions on the set of resources. |
required | object (v1ResourceSet) Set of resources to check |
includeMeta | boolean Opt to receive request processing metadata in the response. |
object (cerbosrequestv1AuxData) Structured auxiliary data useful for evaluating the request |
Responses
Response Schema: application/json
requestId | string Request ID provided in the request. |
object Results for each resource instance, keyed by the ID supplied in the request | |
object (v1CheckResourceSetResponseMeta) Metadata about request evaluation. |
Request samples
- Payload
{- "actions": [
- "view:public",
- "comment"
], - "principal": {
- "id": "bugs_bunny",
- "roles": [
- "user"
]
}, - "resource": {
- "kind": "album:object",
- "instances": {
- "XX125": {
- "attr": {
- "owner": "bugs_bunny",
- "public": false,
- "flagged": false
}
}, - "XX225": {
- "attr": {
- "owner": "daffy_duck",
- "public": true,
- "flagged": false
}
}
}
}
}
Response samples
- 200
- default
{- "requestId": "c2db17b8-4f9f-4fb1-acfd-9162a02be42b",
- "resourceInstances": {
- "XX125": {
- "actions": {
- "view:*": "EFFECT_ALLOW",
- "comment": "EFFECT_ALLOW"
}
}, - "XX225": {
- "actions": {
- "view:*": "EFFECT_DENY",
- "comment": "EFFECT_DENY"
}
}
}, - "meta": {
- "resourceInstances": {
- "XX125": {
- "actions": {
- "view:*": {
- "matched_policy": "album:object:default"
}, - "comment": {
- "matched_policy": "album:object:default"
}
}, - "effective_derived_roles": [
- "owner"
]
}, - "XX225": {
- "actions": {
- "view:*": {
- "matched_policy": "album:object:default"
}, - "comment": {
- "matched_policy": "album:object:default"
}
}
}
}
}
}
Check resources
Check a principal's permissions to a batch of heterogeneous resources and actions.
Request Body schema: application/jsonrequired
Check resources request
requestId | string Optional application-specific ID useful for correlating logs for analysis. |
includeMeta | boolean Add request processing metadata to the response. |
required | object (enginev1Principal) A person or application attempting to perform the actions on the set of resources. |
required | Array of objects (CheckResourcesRequestResourceEntry) non-empty unique List of resources and actions. |
object (cerbosrequestv1AuxData) Structured auxiliary data useful for evaluating the request |
Responses
Response Schema: application/json
requestId | string Request ID provided in the request. |
Array of objects (CheckResourcesResponseResultEntry) Result for each resource | |
cerbosCallId | string Audit log call ID associated with this request |
Request samples
- Payload
{- "principal": {
- "id": "bugs_bunny",
- "roles": [
- "user"
]
}, - "resources": [
- {
- "actions": [
- "view",
- "comment"
], - "resource": {
- "kind": "album:object",
- "policyVersion": "default",
- "id": "XX125",
- "attr": {
- "owner": "bugs_bunny",
- "public": false,
- "flagged": false
}
}
}
]
}
Response samples
- 200
- default
{- "requestId": "c2db17b8-4f9f-4fb1-acfd-9162a02be42b",
- "results": [
- {
- "resource": {
- "Id": "XX125",
- "kind": "album:object"
}, - "actions": {
- "view": "EFFECT_ALLOW",
- "comment": "EFFECT_DENY"
}
}
], - "cerbosCallId": "string"
}
Check resource batch Deprecated
[Deprecated: Use CheckResources API instead] Check a principal's permissions to a batch of heterogeneous resources and actions.
Request Body schema: application/jsonrequired
PDP Request
requestId | string Optional application-specific ID useful for correlating logs for analysis. |
required | object (enginev1Principal) A person or application attempting to perform the actions on the set of resources. |
required | Array of objects (CheckResourceBatchRequestBatchEntry) non-empty unique List of resources and actions. |
object (cerbosrequestv1AuxData) Structured auxiliary data useful for evaluating the request |
Responses
Response Schema: application/json
requestId | string Request ID provided in the request. |
Array of objects (v1CheckResourceBatchResponseActionEffectMap) Result for each resource |
Request samples
- Payload
{- "principal": {
- "id": "bugs_bunny",
- "roles": [
- "user"
]
}, - "resources": [
- {
- "actions": [
- "view",
- "comment"
], - "resource": {
- "kind": "album:object",
- "policyVersion": "default",
- "id": "XX125",
- "attr": {
- "owner": "bugs_bunny",
- "public": false,
- "flagged": false
}
}
}
]
}
Response samples
- 200
- default
{- "requestId": "c2db17b8-4f9f-4fb1-acfd-9162a02be42b",
- "results": [
- {
- "resourceId": "XX125",
- "actions": {
- "view": "EFFECT_ALLOW"
}
}
]
}
Plan resources
Produce a query plan with conditions that must be satisfied for accessing a set of instances of a resource
Request Body schema: application/jsonrequired
PDP Resources Query Plan Request
requestId | string Optional application-specific ID useful for correlating logs for analysis. |
action | string Action to be applied to each resource in the list. |
actions | Array of strings unique List of actions to generate the query plan for. Mutually exclusive with the singular action field. Must contain at least one action and all actions must be unique. |
required | object (enginev1Principal) A person or application attempting to perform the actions on the set of resources. |
required | object (v1PlanResourcesInputResource) |
object (cerbosrequestv1AuxData) Structured auxiliary data useful for evaluating the request | |
includeMeta | boolean Opt to receive request processing metadata in the response. |
Responses
Response Schema: application/json
requestId | string Request ID provided in the request. |
action | string |
actions | Array of strings Actions |
resourceKind | string Resource kind. |
policyVersion | string The policy version. |
object (v1PlanResourcesFilter) | |
object (v1PlanResourcesResponseMeta) Metadata about request evaluation. | |
Array of objects (v1ValidationError) List of validation errors (if schema validation is enabled) | |
cerbosCallId | string Audit log call ID associated with this request |
Request samples
- Payload
{- "principal": {
- "id": "bugs_bunny",
- "roles": [
- "user"
]
}, - "resource": {
- "kind": "album:object"
}
}
Response samples
- 200
- default
{- "requestId": "c2db17b8-4f9f-4fb1-acfd-9162a02be42b",
- "action": "string",
- "actions": [
- "view:public",
- "edit:profile"
], - "resourceKind": "album:object",
- "policyVersion": "default",
- "filter": {
- "kind": "KIND_UNSPECIFIED",
- "condition": {
- "value": null,
- "expression": {
- "operator": "string",
- "operands": [
- { }
]
}, - "variable": "string"
}
}, - "meta": {
- "filterDebug": "string",
- "matchedScope": "string",
- "matchedScopes": {
- "property1": "string",
- "property2": "string"
}
}, - "validationErrors": [
- {
- "path": "string",
- "message": "string",
- "source": "SOURCE_UNSPECIFIED"
}
], - "cerbosCallId": "string"
}
List audit log entries
path Parameters
kind required | string Enum: "KIND_UNSPECIFIED" "KIND_ACCESS" "KIND_DECISION" Kind of log entry |
query Parameters
tail | integer <int64> Last N entries. |
between.start required | string <date-time> Start date in ISO 8601 format. |
between.end required | string <date-time> End date in ISO 8601 format. |
since | string Entries since N hours/minutes ago |
lookup | string^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$ By Call ID |
Responses
Response Schema: application/json
object (v1ListAuditLogEntriesResponse) Audit log stream. | |
object (googlerpcStatus) |
Response samples
- 200
- default
{- "result": {
- "accessLogEntry": {
- "callId": "string",
- "timestamp": "2019-08-24T14:15:22Z",
- "peer": {
- "address": "string",
- "authInfo": "string",
- "userAgent": "string",
- "forwardedFor": "string"
}, - "metadata": {
- "property1": {
- "values": [
- "string"
]
}, - "property2": {
- "values": [
- "string"
]
}
}, - "method": "string",
- "statusCode": 0,
- "oversized": true
}, - "decisionLogEntry": {
- "callId": "string",
- "timestamp": "2019-08-24T14:15:22Z",
- "peer": {
- "address": "string",
- "authInfo": "string",
- "userAgent": "string",
- "forwardedFor": "string"
}, - "inputs": [
- {
- "requestId": "string",
- "resource": {
- "kind": "album:photo",
- "policyVersion": "default",
- "id": "XX125",
- "attr": {
- "owner": "bugs_bunny"
}, - "scope": "acme.corp"
}, - "principal": {
- "id": "bugs_bunny",
- "policyVersion": "default",
- "roles": [
- "user"
], - "attr": {
- "beta_tester": true
}, - "scope": "acme.corp"
}, - "actions": [
- "string"
], - "auxData": {
- "jwt": {
- "property1": null,
- "property2": null
}
}
}
], - "outputs": [
- {
- "requestId": "string",
- "resourceId": "string",
- "actions": {
- "property1": {
- "effect": "EFFECT_UNSPECIFIED",
- "policy": "string",
- "scope": "string"
}, - "property2": {
- "effect": "EFFECT_UNSPECIFIED",
- "policy": "string",
- "scope": "string"
}
}, - "effectiveDerivedRoles": [
- "string"
], - "validationErrors": [
- {
- "path": "string",
- "message": "string",
- "source": "SOURCE_UNSPECIFIED"
}
], - "outputs": [
- {
- "src": "resource.expense.v1/acme#rule-001",
- "val": "some_string"
}
]
}
], - "error": "string",
- "checkResources": {
- "inputs": [
- {
- "requestId": "string",
- "resource": {
- "kind": "album:photo",
- "policyVersion": "default",
- "id": "XX125",
- "attr": {
- "owner": "bugs_bunny"
}, - "scope": "acme.corp"
}, - "principal": {
- "id": "bugs_bunny",
- "policyVersion": "default",
- "roles": [
- "user"
], - "attr": {
- "beta_tester": true
}, - "scope": "acme.corp"
}, - "actions": [
- "string"
], - "auxData": {
- "jwt": {
- "property1": null,
- "property2": null
}
}
}
], - "outputs": [
- {
- "requestId": "string",
- "resourceId": "string",
- "actions": {
- "property1": {
- "effect": "EFFECT_UNSPECIFIED",
- "policy": "string",
- "scope": "string"
}, - "property2": {
- "effect": "EFFECT_UNSPECIFIED",
- "policy": "string",
- "scope": "string"
}
}, - "effectiveDerivedRoles": [
- "string"
], - "validationErrors": [
- {
- "path": "string",
- "message": "string",
- "source": "SOURCE_UNSPECIFIED"
}
], - "outputs": [
- {
- "src": "resource.expense.v1/acme#rule-001",
- "val": "some_string"
}
]
}
], - "error": "string"
}, - "planResources": {
- "input": {
- "requestId": "string",
- "action": "string",
- "actions": [
- "string"
], - "principal": {
- "id": "bugs_bunny",
- "policyVersion": "default",
- "roles": [
- "user"
], - "attr": {
- "beta_tester": true
}, - "scope": "acme.corp"
}, - "resource": {
- "kind": "album:object",
- "attr": {
- "property1": null,
- "property2": null
}, - "policyVersion": "default",
- "scope": "^(0(\\.)*)*$"
}, - "auxData": {
- "jwt": {
- "property1": null,
- "property2": null
}
}, - "includeMeta": true
}, - "output": {
- "requestId": "string",
- "action": "string",
- "kind": "string",
- "policyVersion": "string",
- "scope": "string",
- "filter": {
- "kind": "KIND_UNSPECIFIED",
- "condition": {
- "value": null,
- "expression": {
- "operator": "string",
- "operands": [
- { }
]
}, - "variable": "string"
}
}, - "filterDebug": "string",
- "validationErrors": [
- {
- "path": "string",
- "message": "string",
- "source": "SOURCE_UNSPECIFIED"
}
], - "actions": [
- "string"
], - "matchedScopes": {
- "property1": "string",
- "property2": "string"
}
}, - "error": "string"
}, - "metadata": {
- "property1": {
- "values": [
- "string"
]
}, - "property2": {
- "values": [
- "string"
]
}
}, - "auditTrail": {
- "effectivePolicies": {
- "property1": {
- "attributes": {
- "property1": null,
- "property2": null
}
}, - "property2": {
- "attributes": {
- "property1": null,
- "property2": null
}
}
}
}, - "oversized": true
}
}, - "error": {
- "code": 0,
- "message": "string",
- "details": [
- {
- "@type": "string",
- "property1": null,
- "property2": null
}
]
}
}
List policies
query Parameters
includeDisabled | boolean Include disabled policies |
nameRegexp | string Filter policies by name with regexp |
scopeRegexp | string Filter policies by scope with regexp |
versionRegexp | string Filter policies by version with regexp |
policyId | Array of strings For blob, disk, git stores use file name ( |
Responses
Response Schema: application/json
policyIds | Array of strings |
Response samples
- 200
- default
{- "policyIds": [
- "string"
]
}
Inspect policies
query Parameters
includeDisabled | boolean Include disabled policies |
nameRegexp | string Filter policies by name with regexp |
scopeRegexp | string Filter policies by scope with regexp |
versionRegexp | string Filter policies by version with regexp |
policyId | Array of strings For blob, disk, git stores use file name ( |
Responses
Response Schema: application/json
object |
Response samples
- 200
- default
{- "results": {
- "property1": {
- "actions": [
- "string"
], - "variables": [
- {
- "name": "string",
- "value": "string",
- "kind": "KIND_UNSPECIFIED",
- "source": "string",
- "used": true
}
], - "policyId": "string",
- "derivedRoles": [
- {
- "name": "string",
- "kind": "KIND_UNSPECIFIED",
- "source": "string"
}
], - "attributes": [
- {
- "kind": "KIND_UNSPECIFIED",
- "name": "string"
}
], - "constants": [
- {
- "name": "string",
- "value": null,
- "kind": "KIND_UNSPECIFIED",
- "source": "string",
- "used": true
}
]
}, - "property2": {
- "actions": [
- "string"
], - "variables": [
- {
- "name": "string",
- "value": "string",
- "kind": "KIND_UNSPECIFIED",
- "source": "string",
- "used": true
}
], - "policyId": "string",
- "derivedRoles": [
- {
- "name": "string",
- "kind": "KIND_UNSPECIFIED",
- "source": "string"
}
], - "attributes": [
- {
- "kind": "KIND_UNSPECIFIED",
- "name": "string"
}
], - "constants": [
- {
- "name": "string",
- "value": null,
- "kind": "KIND_UNSPECIFIED",
- "source": "string",
- "used": true
}
]
}
}
}
Get policy
query Parameters
id required | Array of strings For blob, disk, git stores use file name ( |
Responses
Response Schema: application/json
Array of objects (v1Policy) |
Response samples
- 200
- default
{- "policies": [
- {
- "apiVersion": "string",
- "disabled": true,
- "description": "string",
- "metadata": {
- "sourceFile": "string",
- "annotations": {
- "property1": "string",
- "property2": "string"
}, - "hash": "string",
- "storeIdentifer": "string",
- "storeIdentifier": "string",
- "sourceAttributes": {
- "attributes": {
- "property1": null,
- "property2": null
}
}
}, - "resourcePolicy": {
- "resource": "string",
- "version": "string",
- "importDerivedRoles": [
- "string"
], - "rules": [
- {
- "actions": [
- "string"
], - "derivedRoles": [
- "string"
], - "roles": [
- "string"
], - "condition": {
- "match": {
- "all": {
- "of": [
- null
]
}, - "any": {
- "of": [
- null
]
}, - "none": {
- "of": [
- null
]
}, - "expr": "string"
}, - "script": "string"
}, - "effect": "EFFECT_UNSPECIFIED",
- "name": "string",
- "output": {
- "expr": "string",
- "when": {
- "ruleActivated": "string",
- "conditionNotMet": "string"
}
}
}
], - "scope": "string",
- "schemas": {
- "principalSchema": {
- "ref": "string",
- "ignoreWhen": {
- "actions": [
- "string"
]
}
}, - "resourceSchema": {
- "ref": "string",
- "ignoreWhen": {
- "actions": [
- "string"
]
}
}
}, - "variables": {
- "import": [
- "string"
], - "local": {
- "property1": "string",
- "property2": "string"
}
}, - "scopePermissions": "SCOPE_PERMISSIONS_UNSPECIFIED",
- "constants": {
- "import": [
- "string"
], - "local": {
- "property1": null,
- "property2": null
}
}
}, - "principalPolicy": {
- "principal": "string",
- "version": "string",
- "rules": [
- {
- "resource": "string",
- "actions": [
- {
- "action": "string",
- "condition": {
- "match": {
- "all": null,
- "any": null,
- "none": null,
- "expr": null
}, - "script": "string"
}, - "effect": "EFFECT_UNSPECIFIED",
- "name": "string",
- "output": {
- "expr": "string",
- "when": {
- "ruleActivated": null,
- "conditionNotMet": null
}
}
}
]
}
], - "scope": "string",
- "variables": {
- "import": [
- "string"
], - "local": {
- "property1": "string",
- "property2": "string"
}
}, - "scopePermissions": "SCOPE_PERMISSIONS_UNSPECIFIED",
- "constants": {
- "import": [
- "string"
], - "local": {
- "property1": null,
- "property2": null
}
}
}, - "derivedRoles": {
- "name": "string",
- "definitions": [
- {
- "name": "string",
- "parentRoles": [
- "string"
], - "condition": {
- "match": {
- "all": {
- "of": [
- null
]
}, - "any": {
- "of": [
- null
]
}, - "none": {
- "of": [
- null
]
}, - "expr": "string"
}, - "script": "string"
}
}
], - "variables": {
- "import": [
- "string"
], - "local": {
- "property1": "string",
- "property2": "string"
}
}, - "constants": {
- "import": [
- "string"
], - "local": {
- "property1": null,
- "property2": null
}
}
}, - "exportVariables": {
- "name": "string",
- "definitions": {
- "property1": "string",
- "property2": "string"
}
}, - "rolePolicy": {
- "role": "string",
- "parentRoles": [
- "string"
], - "scope": "string",
- "rules": [
- {
- "resource": "string",
- "allowActions": [
- "string"
], - "condition": {
- "match": {
- "all": {
- "of": [
- null
]
}, - "any": {
- "of": [
- null
]
}, - "none": {
- "of": [
- null
]
}, - "expr": "string"
}, - "script": "string"
}
}
], - "scopePermissions": "SCOPE_PERMISSIONS_UNSPECIFIED"
}, - "exportConstants": {
- "name": "string",
- "definitions": {
- "property1": null,
- "property2": null
}
}, - "variables": {
- "property1": "string",
- "property2": "string"
}, - "$schema": "string"
}
]
}
Add or update policies
Request Body schema: application/jsonrequired
Add/update policy request
required | Array of objects (v1Policy) [ 1 .. 100 ] items List of policies. |
Responses
Response Schema: application/json
success | object |
Request samples
- Payload
{- "policies": [
- { }
]
}
Response samples
- 200
- default
{- "success": { }
}
Add or update policies
Request Body schema: application/jsonrequired
Add/update policy request
required | Array of objects (v1Policy) [ 1 .. 100 ] items List of policies. |
Responses
Response Schema: application/json
success | object |
Request samples
- Payload
{- "policies": [
- { }
]
}
Response samples
- 200
- default
{- "success": { }
}
Disable policy
Request Body schema: application/jsonrequired
Disable policy request
id required | Array of strings Unique identifier for the policy |
Responses
Response Schema: application/json
disabledPolicies | integer <int64> |
Request samples
- Payload
{- "id": "principal.sarah.vdefault"
}
Response samples
- 200
- default
{- "disabledPolicies": 0
}
Enable policy
Request Body schema: application/jsonrequired
Enable policy request
id required | Array of strings Unique identifier for the policy |
Responses
Response Schema: application/json
enabledPolicies | integer <int64> |
Request samples
- Payload
{- "id": "principal.sarah.vdefault"
}
Response samples
- 200
- default
{- "enabledPolicies": 0
}
Get schema
query Parameters
id required | Array of strings Unique identifier for the schema |
Responses
Response Schema: application/json
Array of objects (schemav1Schema) |
Response samples
- 200
- default
{- "schemas": [
- {
- "id": "principal.json",
- "definition": {
- "type": "object",
- "properties": { }
}
}
]
}
Add or update schema
Request Body schema: application/jsonrequired
Add/update schema request
required | Array of objects (schemav1Schema) [ 1 .. 100 ] items List of schemas. |
Responses
Response Schema: application/json
Add/update schema response
Request samples
- Payload
{- "schemas": [
- {
- "id": "principal.json",
- "definition": {
- "type": "object",
- "properties": { }
}
}
]
}
Response samples
- 200
- default
{ }
Add or update schema
Request Body schema: application/jsonrequired
Add/update schema request
required | Array of objects (schemav1Schema) [ 1 .. 100 ] items List of schemas. |
Responses
Response Schema: application/json
Add/update schema response
Request samples
- Payload
{- "schemas": [
- {
- "id": "principal.json",
- "definition": {
- "type": "object",
- "properties": { }
}
}
]
}
Response samples
- 200
- default
{ }