API Reference: Write

Write Requests provide the ability to create, modify, or delete the relationships stored in Authzed.

Clients may modify a single relation tuple to add or remove an ACL. They may also modify all tuples related to an object via a read-modify-write process with optimistic concurrency control that uses a read RPC followed by a Write RPC:

  1. Read all relation tuples of an object, including a per-object "lock" tuple.
  2. Generate the tuples to write or delete. Send the writes, along with a touch on the lock tuple, to Zanzibar, with the condition that the writes will be committed only if the lock tuple has not been modified since the read.
  3. If the write condition is not met, go back to step 1. The lock tuple is just a regular relation tuple used by clients to detect write races.

gRPC Endpoint#

ACLService.Write

Request#

Parameters#

NameTypeRequired
write_conditionsRelationTupleUpdateNo
updatesRelationTupleYes

Request Definition#

message WriteRequest {
repeated RelationTuple write_conditions = 1;
repeated RelationTupleUpdate updates = 2;
}
Additional Protocol Buffer definitions used
message RelationTupleUpdate {
enum Operation { UNKNOWN = 0; CREATE = 1; TOUCH = 2; DELETE = 3; }
Operation operation = 1;
RelationTuple tuple = 2;
}
message RelationTuple {
ObjectAndRelation object_and_relation = 1;
User user = 2;
}
message ObjectAndRelation {
string namespace = 1;
string object_id = 2;
string relation = 3;
}
message User {
oneof user_oneof {
uint64 user_id = 1;
ObjectAndRelation userset = 2;
}
}

Request Example#

Adding user with ID 213 as an editor and on a note:

{
updates: [
{
operation: 1,
tuple: {
object_and_relation: {
namespace: "mynotetakingapp/note"
object_id: "2112"
relation: "editor"
}
user: {
userset: {
namespace: "mynotetakingapp/user"
object_id: "213"
relation: "..."
}
}
}
}
]
}

Response#

Response Definition#

message WriteResponse { Zookie revision = 1; }
message Zookie { string token = 1; }

Response Example#

{
revision { token: "CAESAggB" }
}

Errors#

  • INVALID_ARGUMENT: a provided value has failed to semantically validate
  • FAILED_PRECONDITION: a specified write_condition was not true or a provided 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 containing the object to check
Object IDThe ID of the object to check
RelationThe relation to check for the object
User namespaceThe namespace for users in your tenant
User IDThe ID of the user against which to check
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 \
'{
"updates": [
{
"operation": 1,
"tuple": {
"object_and_relation": {
"namespace": "someslug/note",
"object_id": "grocerylist",
"relation": "viewer"
},
"user": {
"userset": {
"namespace": "someslug/user",
"object_id": "213",
"relation": "..."
}
}
}
}
]
}' \
grpc.authzed.com:443 ACLService.Write