Concepts: Lookup API

An Lookup call is a call to the Authzed API to lookup all the objects under a relation for which a particular user is a member.

Lookup calls are usually used when you need to learn the membership of a relation for a particular user: By calling Lookup, a list of object IDs is returned for which the Check for the specified relation and user would succeed.

Forming a Lookup#

An Lookup call is formed by specifying the relation on which to lookup, along with the user for whom to perform the lookup.

Making the Lookup call#

To make an lookup call, issue an LookupRequest to the API:

LookupRequest {
object_relation: RelationReference {
namespace: 'thetenant/document'
relation: 'viewer'
user: ObjectAndRelation {
namespace: 'thetenant/user'
object_id: 'someuser'
relation: '...'

The Lookup call will return the list of object IDs for which the user has access:

For example, imagine if we had this namespace:

name: "thetenant/document"
relation {
name: "view"

Calling Lookup on view for a user someuser would return something along the lines of:

LookupResponse {
resolved_object_ids: ['firstdocument', 'seconddocument']

This represents the set of document's on which the user someuser can view.