Zanzibar (Relationship-Based Authorization)

Zanzibar is the relationship-based authorization model described in Google's 2019 paper. Instead of assigning roles globally, Zanzibar stores relation tuples of the form object#relation@subject — for example document:readme#editor@user:alice ("alice is an editor of document readme"). An authorization check asks "is there a path in the relation graph from this subject to this object under this relation, given the schema's rewrite rules?".

Use Zanzibar when access is driven by hierarchy and relationships: folders containing files, teams owning projects, organizations containing workspaces. Inheritance ("editors of a folder can edit its documents") and sharing ("all members of this team can view this document") are natural in Zanzibar and awkward to express in RBAC.

What is Zanzibar?

Zanzibar stores relationships between subjects and objects. Each relationship is a single tuple. A check walks the graph formed by those tuples, following the schema's userset rewrites.

Traditional RBAC	Zanzibar
"Alice is an editor" (globally)	"Alice is an editor of Document X"
"Bob is a viewer" (globally)	"Bob is a member of Team A, and Team A has view access on Project Y"

This answers fine-grained, per-object questions:

"Can Alice edit this specific document?"
"Can Bob view this project because his team has access?"
"Who can access this file?"

Core Concepts

Relation Tuples

A relation tuple is the fundamental unit of Zanzibar. It describes a relationship between a subject and an object:

object#relation@subject

Component	Description	Example
Object	The resource (namespace:id)	`document:readme`
Relation	The type of relationship	`editor`
Subject	A user or a userset	`user:alice` or `group:eng#member`

Example tuples:

document:readme#editor@user:alice          # Alice is editor of readme
document:readme#viewer@group:engineering   # Engineering group can view readme
folder:docs#owner@user:bob                 # Bob owns the docs folder
team:backend#member@user:carol             # Carol is a member of backend team

A subject can be a concrete identity (user:alice) or a userset — a reference to every entity holding a given relation on another object, written object#relation. For example group:engineering#member means "every user who is a member of group:engineering". Userset subjects let you grant access to whole groups in a single tuple.

Namespace Definitions

A namespace defines the valid relations and permission rewrites for a type of object:

namespace: document
  relations:
    owner:
      - user
    editor:
      - user
      - group#member
    viewer:
      - user
      - group#member
  permissions:
    can_edit:
      union:
        - owner
        - editor
    can_view:
      union:
        - can_edit
        - viewer
    can_delete:
      - owner

This declares:

owner, editor, and viewer are valid relations for documents.
can_edit = owner OR editor (userset rewrite).
can_view = can_edit OR viewer (so editors can also view).
can_delete = owner only.

Check and Expand

Two operations drive Zanzibar:

Check — "does subject S have relation R on object O?" The engine searches the graph, following rewrite rules, and returns a yes/no.
Expand — "what is the full tree of subjects that hold relation R on object O?" Useful for audit screens and for computing lists such as "everyone who can view this document".

Permission Inheritance

Relations compose through the graph. Given:

folder:docs#owner@user:bob
folder:docs#parent@folder:root
document:readme#parent@folder:docs

and a schema rule "folder owners can view all documents in the folder", Bob can view document:readme — the check follows the parent edges up the tree.

Managing Zanzibar

Portal

Navigate to /orgs/{orgId}/portal/access-management/zanzibar:

Namespaces — define object types and their relations.
Relation Tuples — create and manage relationships.
Check — test a subject's permission on an object.
Expand — list every subject that holds a given permission on an object.
List Objects — find every object a subject can access.

Creating Relation Tuples

Go to /orgs/{orgId}/portal/access-management/zanzibar.
Click Create Tuple.
Enter:
- Object — the resource (e.g., document:readme).
- Relation — the relationship (e.g., editor).
- Subject — the user or userset (e.g., user:alice or group:engineering#member).

Via API

# Create a relation tuple
curl -X POST https://your-domain.com/api/v1/zanzibar/tuples \
  -H "Authorization: Bearer {admin_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "object": "document:readme",
    "relation": "editor",
    "subject": "user:alice"
  }'

# Check permission
curl -X POST https://your-domain.com/api/v1/authz/zanzibar/check \
  -H "Authorization: Bearer {admin_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "object": "document:readme",
    "permission": "can_edit",
    "subject": "user:alice"
  }'
# Response: {"allowed": true}

# List objects a user can access
curl -X POST https://your-domain.com/api/v1/zanzibar/list-objects \
  -H "Authorization: Bearer {admin_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "user:alice",
    "permission": "can_view",
    "object_type": "document"
  }'

Examples

# Bob owns a folder
folder:shared-docs#owner@user:bob

# Alice can edit files in the folder
folder:shared-docs#editor@user:alice

# The engineering group can view
folder:shared-docs#viewer@group:engineering

# A document is in the folder
document:design-doc#parent@folder:shared-docs

Organization Hierarchy

# Carol is a member of the backend team
team:backend#member@user:carol

# Backend team belongs to the engineering organization
org:engineering#team@team:backend

# Engineering org has access to the production environment
environment:production#accessor@org:engineering#member

# Carol can access production through: team → org → environment

Multi-Organization SaaS

# Acme Corp's workspace
workspace:acme#admin@user:alice
workspace:acme#member@user:bob

# Project within the workspace
project:api-v2#parent@workspace:acme
project:api-v2#lead@user:bob

# Bob is project lead AND workspace member
# Alice is workspace admin, so she can access all projects

Zanzibar vs RBAC

Aspect	RBAC	Zanzibar
Granularity	Role-level	Object-level
Scale	Hundreds of roles	Large relation graphs
Questions answered	"What can this user do?"	"Can this user do X to object Y?"
Maintenance	Manage roles and assignments	Manage relation tuples
Best for	Application-wide permissions	Per-resource permissions

Best Practices

Practice	Description
Design namespaces carefully	Model domain objects and their natural relationships
Use inheritance over duplication	Prefer `parent` relations to copying tuples
Grant to groups, not individuals	Use userset subjects for team access
Test with the Permission Tester	Verify expected decisions before rolling out
Start small	Begin with a few relations, extend as you learn the domain

Roles & Permissions — application-wide RBAC.
ABAC — attribute and context conditions.
AI Policy Authoring — generate Zanzibar namespaces from plain English.
Access Control Overview — compare all authorization models.

What is Zanzibar?​

Core Concepts​

Relation Tuples​

Namespace Definitions​

Check and Expand​

Permission Inheritance​

Managing Zanzibar​

Portal​

Creating Relation Tuples​

Via API​

Examples​

Google Drive-Style Sharing​

Organization Hierarchy​

Multi-Organization SaaS​

Zanzibar vs RBAC​

Best Practices​

Related​