API Reference: Lookup

Lookup Requests provide the ability to list the objects for a particular relation and user.

gRPC Endpoint#

ACLService.Lookup

Request#

Parameters#

note

It is recommended to specify the at_revision Zookie value, which will return the data as of the logical timestamp represented by that Zookie.

NameTypeRequired
object_relationRelationReferenceYes
userObjectAndRelationYes
at_revisionZookieNo (but recommended)

Request Definition#

message LookupRequest {
RelationReference object_relation = 1;
ObjectAndRelation user = 2;
Zookie at_revision = 3;
}
Additional Protocol buffer definitions used
message ObjectAndRelation {
string namespace = 1;
string object_id = 2;
string relation = 3;
}
message RelationReference {
string namespace = 1;
string relation = 3;
}
message Zookie { string token = 1; }

Request Example#

{
user: {
namespace: "mynotetakingapp/user"
object_id: "someuserid"
relation: "..."
}
object_relation: {
namespace: "mynotetakingapp/note"
relation: "viewer"
}
at_revision: { token: "CAESAggB" }
}

Response#

Response Definition#

message LookupResponse {
repeated string resolved_object_ids = 1;
Zookie revision = 3;
}

Response Example#

{
resolved_object_ids {
'2112',
'3133',
}
revision { token: "CAESAggG" }
}

Errors#

  • INVALID_ARGUMENT: a provided value has failed to semantically validate
  • RESOURCE_EXHAUSTED: processing the request surpassed the maximum depth of relationship resolution
  • FAILED_PRECONDITION: a specified namespace or relation does not exist

For more generic failures, see the gRPC Status Code documentation.

Code Samples#

Code Sample Parameter Values
Parameter NameValueDescription
Tenant SlugThe slug for your tenant
TokenYour token
User NamespaceThe namespace of the user
User IDThe ID of the user
NamespaceThe namespace for the relation for which to lookup
RelationThe relation for which to lookup
ZookieThe opaque token that signifies a read should be as fresh as the write that produced this token.
grpcurl -rpc-header "authorization: Bearer t_my_token" -d \
'{
"object_relation": {
"namespace": "someslug/mynamespace",
"relation": "viewer"
},
"user": {
"namespace": "someslug/mynamespace",
"object_id": "someuser",
"relation": "..."
},
"at_revision": { "token": "someopaquevalue" }
}' \
grpc.authzed.com:443 ACLService/Expand