Inside Zanzibar: How Relationship Tuples and Consistency Tokens Make Authorization Global
A source-grounded tour of Google Zanzibar’s relationship model, consistency tokens, and the engineering problem behind safe distributed permission checks.
On this page

A permission check often looks like a boolean: can this user read this document? The difficult case is the sequence around that boolean. A user is removed from a group, a file is shared, or an object moves between containers while replicas and caches are serving checks. The Zanzibar paper presents a global authorization system designed to preserve causal ordering across those changes. [1]
Represent access as relationships
A relationship model describes facts such as “document 42 is in folder 9,” “folder 9 is shared with group engineering,” or “Ari is a member of engineering.” The policy says which paths through those facts grant a requested relation. A check asks whether a subject has a relation to an object under the selected policy model.
This expresses inheritance and group membership without copying every derived permission onto every document. It also makes the authorization graph a dependency: changing a group edge or a parent relationship can affect many checks. The system therefore needs versioned policy data, bounded query work, and a way to reason about what a reader is allowed to observe after a write.
Zanzibar’s paper describes a tuple-oriented data model and a configuration language for relationships. The model is broader than traditional role assignment, but it does not make roles obsolete. A role can be one relation in a policy; the system’s job is to evaluate the relationships and policy rules that determine the final check. [1]
The new-enemy race
Imagine a document owner removes Pat from a group and then tells Lee that Pat no longer has access. If Lee writes sensitive content while a later authorization check is served from a replica that has not observed the removal, Pat could still read that content. The security problem is not simply “eventual consistency is bad.” It is that a particular user action creates an ordering promise: after the removal is acknowledged, subsequent actions that rely on the removal must not be evaluated against an older ACL snapshot.
The Zanzibar design addresses this with consistency tokens called zookies. A write returns a token representing a point in the system’s change history. A client that needs a later check to reflect that write can pass the token as a freshness requirement. The server can then select a sufficiently recent snapshot or wait until it is available. The token is opaque to the client; it is not a permission itself and should not be treated as a user credential. [1]
This is an application of causal ordering. It lets a product say, in effect, “this check must include at least the policy change that just completed,” without requiring every unrelated permission read to serialize against every newest write.
Freshness is a product decision
Not every read has the same consistency need. A UI showing a low-risk list may tolerate bounded staleness for a short interval. A workflow that confirms a user has just lost access may require a check that observes the relevant revocation. Zanzibar exposes consistency choices rather than pretending one read policy fits all calls.
That choice must be part of the caller’s behavior. If a write returns a consistency token and a subsequent security-sensitive action ignores it, the application may have lost the ordering guarantee it expected. If every request always demands the newest global snapshot, availability and latency can suffer. The policy is therefore an explicit product contract, not an implementation detail hidden inside a cache.
What the system’s reported scale does—and does not—say
The USENIX paper reports that Zanzibar supported trillions of access-control lists and millions of authorization requests per second for Google services. It reports 95th-percentile latency below 10 milliseconds and availability above 99.999% over three years of production use. Those are measurements reported by the authors for their deployed system, not a benchmark that can be transferred to a different service or database. [1]
The paper’s scope is also specific. It describes Google’s internal system, including its data model, consistency semantics, and operational experience. It is not a public API specification for Google Cloud IAM, and the paper does not establish that another company can reproduce the same outcomes by adopting a relationship graph alone.
A practical design checklist
When building an authorization service, write down the object types and relations first. Identify which relationships inherit access, which group expansions are allowed, and how cycles or very deep paths are bounded. Define what a successful write promises to a caller and how the caller carries that promise into follow-up checks. Test revocation races, group changes, object moves, stale replicas, and cache invalidation as concrete traces.
Also separate authorization from authentication. A valid session says who is making a request; it does not prove that the user may read a particular object. For a closer look at the transport and application boundaries around requests, see our cloud load balancer guide.
Do
- Make freshness requirements explicit for operations that follow ACL changes.
- Model group and parent relationships as policy inputs with bounded evaluation.
- Treat reported production scale as evidence about Zanzibar, not a promise for another deployment.
Don't
- Do not use a consistency token as an authorization credential.
- Do not assume a cache invalidation message alone enforces a user-visible ordering promise.
- Do not equate authentication, roles, and object-level authorization.
The hard part of global authorization is preserving the meaning of a permission change while the system is distributed. Zanzibar’s strongest design lesson is to connect writes and later reads with an explicit consistency contract.
Frequently asked questions
What problem does Zanzibar solve?
Zanzibar is Google's system for storing and evaluating access-control relationships across multiple services. Its paper focuses on consistent authorization decisions as ACL data and protected objects change.
What is a relationship tuple?
A tuple records that a subject, such as a user or group, has a relation to an object, such as a document. Policies can reference other relations to express inheritance and group membership.
What is a zookie?
In the published design, a zookie is an opaque consistency token associated with a Zanzibar write. A client can supply it to a later check to require a sufficiently fresh view relative to that write.
Does Zanzibar mean every permission check is globally linearizable?
The paper describes external consistency and consistency options for checks, including bounded-staleness tradeoffs. It does not mean every read must wait for the newest global state regardless of the requested consistency mode.



/* Comments */
Comments are offline right now — we reconnect automatically, nothing is lost.