LookupSubjects and SpiceDB v1.12.0
Published: 2024-01-10 16:31:38

---
title: LookupSubjects and SpiceDB v1.12.0
published: true
date: 2022-09-20 00:00:00 UTC
tags: 
canonical_url: https://authzed.com/blog/lookup-subjects
---

July and August have been busy months for everyone at Authzed!

In addition to the announcement of the [SpiceDB Operator](/blog/open-source-spicedb-operator/) and the new [WASM based playground](/blog/some-assembly-required/), [SpiceDB](https://github.com/authzed/spicedb) itself received a significant update in the form of [version 1.12](https://github.com/authzed/spicedb/releases/tag/v1.12.0)

Version 1.12 of SpiceDB introduces a number of improvements, the largest of which is a **new API** called [LookupSubjects](https://buf.build/authzed/api/docs/main:authzed.api.v1#authzed.api.v1.PermissionsService.LookupSubjects).

## When to use LookupSubjects

The LookupSubjects API provides the ability to find all subjects reachable for a particular resource and permission, acting as a reverse of our previously released [LookupResources](https://buf.build/authzed/api/docs/main:authzed.api.v1#authzed.api.v1.PermissionsService.LookupResources) API.

LookupSubjects is most useful for any user interface or auditing code that needs to determine the full set of users, tokens, or other kinds of subjects which have a particular permission on a resource.

Unlike the [ExpandPermissionTree](https://buf.build/authzed/api/docs/main:authzed.api.v1#authzed.api.v1.PermissionsService.ExpandPermissionTree) API, LookupSubjects is automatically recursive: it will walk through other kinds of objects, such as groups, to determine the fully resolved set of subjects that have the requested permission. Also unlike the Expand API, LookupSubjects is **streaming** : it will return results as soon as it can to the caller.

For example, a "who can view this document" panel might use LookupSubjects to determine the full set of users that can view the document, including those who gain access through groups, or a parent organization:

```
LookupSubjectsRequest {
  Resource: {
    ObjectType: "document"
    ObjectId: "thedocument"
  }

  Permission: "view"

  SubjectObjectType: "user"
}

```

## How LookupSubjects works

In my [ACL Filtering in Authzed](https://authzed.com/blog/acl-filtering-in-authzed/) blog post, I discussed how LookupResources (the inverse to LookupSubjects) functions by walking the permission graph in a "backwards" fashion.

LookupSubjects functions in much the same way, but in the same direction as a [Check](https://authzed.com/blog/check-it-out/): starting at the permission requested and the resource type, SpiceDB walks **all** branches of the permission graph, outward, until it reaches any subjects of the requested type:

<iframe src="/helpercontent/blogs/lookup-subjects/animation.html" style="width: 100%; border: 0; height: 510px; overflow: hidden"></iframe>

We chose to add the LookupSubjects API for two reasons:

1. The ability to find all accessible subjects is incredibly important for auditing and other kinds of UI and was difficult to implement for users: previously, this kind of recursive walk and processing would have to be done by clients themselves via multiple Expand calls, which we recognized as a significant hurdle to adoption.

2. LookupSubjects is one of the two APIs (the other being [ReachableResources](https://github.com/authzed/spicedb/blob/main/proto/internal/dispatch/v1/dispatch.proto#L81)) necessary to support the [WatchResources API](https://github.com/authzed/spicedb/issues/207), a new API currently being implemented which will stream a set of permission changes whenever a relationship is updated in SpiceDB. This new API will allow users of SpiceDB to store and update the set of accessible resources for a particular kind of subject, and use that set for filtering via RDBMSes, Elastic, and other external querying systems.

## Test it now

Want to test LookupSubjects now? Simply create an account on [authzed.com](https://app.authzed.com) or download [SpiceDB](https://github.com/authzed/spicedb) and then run a [zed](https://github.com/authzed/zed) call:

```
zed permission lookup-subjects document somedocument view user

```

Have a question? Check out the [Discord](https://authzed.com/discord), where we and the community are discussing all things SpiceDB