API Reference: Expand

Expand Requests provide the ability to list the users in a particular userset.

Unlike Read Responses, Expand Responses follow indirect references. For example, expanding a viewer relation, would also include users with owner relations that viewer includes as a part of a userset_rewrite.

gRPC Endpoint#

ACLService.Expand

Request#

Parameters#

note

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

NameTypeRequired
usersetObjectAndRelationYes
at_revisionZookieNo (but recommended)

Request Definition#

message ExpandRequest {
ObjectAndRelation userset = 1;
Zookie at_revision = 2;
}
Additional Protocol buffer definitions used
message ObjectAndRelation {
string namespace = 1;
string object_id = 2;
string relation = 3;
}
message Zookie { string token = 1; }

Request Example#

{
userset: {
namespace: "mynotetakingapp/note"
object_id: "2112"
relation: "viewer"
}
at_revision: { token: "CAESAggB" }
}

Response#

Response Definition#

message ExpandResponse {
RelationTupleTreeNode tree_node = 1;
Zookie revision = 3;
}
Additional Protocol Buffer definitions used
message RelationTupleTreeNode {
oneof node_type {
SetOperationUserset intermediate_node = 1;
DirectUserset leaf_node = 2;
}
ObjectAndRelation expanded = 3;
}
message SetOperationUserset {
enum Operation { INVALID = 0; UNION = 1; INTERSECTION = 2; EXCLUSION = 3; }
Operation operation = 1;
repeated RelationTupleTreeNode child_nodes = 2;
}
message DirectUserset { repeated User users = 1; }
message ObjectAndRelation {
string namespace = 1;
string object_id = 2;
string relation = 3;
}
message User {
oneof user_oneof {
uint64 user_id = 1;
ObjectAndRelation userset = 2;
}
}
message Zookie { string token = 1; }

Response Example#

{
tree_node {
leaf_node {
users {
userset {
namespace: "mynotetakingapp/user"
object_id: "213"
relation: "..."
}
}
users {
userset {
namespace: "mynotetakingapp/user"
object_id: "539"
relation: "..."
}
}
}
expanded {
namespace: "mynotetakingapp/note"
object_id: "2112"
relation: "viewer"
}
}
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
NamespaceThe namespace of the userset that will be expanded
Object IDThe ID of the object whose userset will be expanded
RelationThe relation of the object that will be expanded
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 \
'{
"userset": {
"namespace": "someslug/mynamespace",
"object_id": "someobject",
"relation": "viewer"
},
"at_revision": { "token": "someopaquevalue" }
}' \
grpc.authzed.com:443 ACLService/Expand