SpiceDB LookupResources: Efficient Bulk Permission Checks

Stop making hundreds of CheckPermission calls. Learn how to use SpiceDB's LookupResources to efficiently retrieve all resources a user can access in a single, paginated request.

The 'What Can I See?' Problem

In a multi-tenant SaaS application, checking if a user has access to a specific resource is straightforward. You call CheckPermission and you get a boolean. The inverse problem, determining every resource a user is allowed to access, is where most permission systems break down.

The naive approach is to fetch every resource ID from your primary database and run a CheckPermission call for each one. If a user has access to 500 documents, that is 500 network round-trips. Even with batching, this puts pressure on the authorization service and creates a latency bottleneck in the UI.

The solution is LookupResources. Instead of asking Can User A see Document B, you ask Which documents can User A see. This shifts the computational burden to SpiceDB's internal indexing, returning a list of resources the user is authorized to access in a single request.

How LookupResources Operates

LookupResources functions as a reverse query. It finds all resources of a specific type that satisfy a given permission for a specific subject.

Because SpiceDB is designed for scale, this API does not perform a full table scan of every tuple in the system. It leverages the graph structure to traverse only the paths that lead to the subject. Performance scales relative to the number of resources the user actually has access to, rather than the total number of resources in the database.

Handling Large Result Sets with Cursors

In enterprise environments, a single user might have access to thousands of resources. To prevent memory exhaustion and network timeouts, SpiceDB uses cursor-based pagination. When a request returns a partial list, it includes a continuation token. To get the next page, the client sends that token back in the subsequent request.

Practical Implementation: Document Access

Consider a schema where users can be viewers of a document. To implement a My Documents dashboard, you would use the following logic.

Schema Definition

definition document {\n  relation viewer: user\n  permission view = viewer\n}

The Lookup Request

To find all documents a user can view, execute the LookupResources RPC from your backend application server using the SpiceDB client library with appropriate API key permissions.

Resource Type: document
Permission: view
Subject: user:anne

Expected Result: A list of resource IDs such as document:doc_1, document:doc_42 and a cursor if more results exist.

Verification Step

To verify the result is accurate, pick one of the returned IDs and run a manual CheckPermission call for that specific resource. The result must be ALLOWED. If LookupResources returns a resource that CheckPermission denies, it indicates a schema mismatch or a cached state inconsistency.

Trade-offs and Limitations

While powerful, LookupResources introduces specific engineering constraints that differ from simple permission checks.

\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n

Factor	CheckPermission	LookupResources
Latency	Constant/Low	Variable based on result size
Consistency	Strongly consistent	Eventually consistent
Complexity	Simple boolean	Paginated stream

The most critical limitation is eventual consistency. Because LookupResources often relies on optimized read paths, a tuple created a few milliseconds ago might not appear in the lookup results immediately. If the application requires absolute real-time visibility for a newly created resource, you may need to manually append that specific resource to the UI list until the lookup index catches up.

Closing the Loop

Moving from a Check-All pattern to a LookupResources pattern transforms the authorization layer from a bottleneck into a discovery engine. To implement this successfully: define clear relations and permissions in the schema, implement cursor-based pagination in your API, and account for the slight delay in eventual consistency for new permissions.

Stop Polling: Using SpiceDB LookupResources for Dynamic Access Lists