Check many permissions with bulk check
Send several permission checks to the policy decision point (PDP) in one request with permit.bulkCheck(). This page is for developers who already call permit.check() and need several decisions in the same request handler.
Prerequisites
- A Permit SDK client connected to a PDP (Run the PDP, or Deploy Nexus PDP for Permit Nexus PDP)
- Your environment API key (Get your API key). On Nexus PDP, use the environment's Nexus PDP API key instead.
- Familiarity with the arguments of
permit.check()
Run a bulk check
Each item in the bulk check takes the same user, action, and resource arguments as permit.check(). Pass the items as an array (a list in Java and Python, variadic CheckRequest values in Go).
| SDK | Function |
|---|---|
| Node.js | permit.bulkCheck(checks, context?) |
| Python | permit.bulk_check(checks, context=None) |
| Java | permit.bulkCheck(List<CheckQuery> checks) |
| Go | permit.BulkCheck(requests ...CheckRequest) |
The SDK sends all items to the PDP in one request. To call the PDP without an SDK, use the POST /allowed/bulk endpoint described in the PDP API reference.
Read the bulk check result
bulkCheck() returns an array of booleans. The result at index i is the decision for the check at index i. In the Node.js example, a result of [true, false, false, true] means Anna can read contracts, Anna can't create documents, John can't sign contracts, and Jane can authorize invoices.
Use cases
Reduce latency when a handler needs several checks
When one API endpoint performs several actions, send all the checks in one bulk call instead of one permit.check() call per action. One request to the PDP replaces several round trips.
Combine ReBAC and ABAC checks for one operation
Some operations depend on two policy models. In this example, a user can edit a document when a relationship-based access control (ReBAC) role on the document grants edit, or when an attribute-based access control (ABAC) rule grants edit to the user's subscription tier. The bulk check sends both checks at once, and the code allows the edit when either result is true.
The Cloud PDP and Nexus PDP don't evaluate ABAC policies. On them, the ABAC item returns a deny, not an error, so only the ReBAC check can allow the edit. Run a container PDP for this example. See Cloud PDP capabilities and Nexus PDP feature parity.
Filter a list of resources
To return only the items a user can read, map each item to a check, run one bulk check, and keep the items whose result is true. For other filtering approaches, see Data filtering.
Raise the PDP query timeout for large bulk checks
A bulk check takes longer to evaluate than a single check. When evaluation exceeds the PDP's query timeout, the PDP returns a timeout error instead of decisions. The PDP_OPA_CLIENT_QUERY_TIMEOUT environment variable sets the timeout in seconds. The default is 1.
To allow 10 seconds, set the variable on the PDP container:
PDP_OPA_CLIENT_QUERY_TIMEOUT=10
If bulk checks still time out, give the PDP more CPU. See PDP_OPA_CLIENT_QUERY_TIMEOUT and System requirements and performance optimization.