chore: re-organize zanzibar bits (#404)

miparnisari · web-flow · commit b23de9ce5070 · 2025-11-10T10:00:30.000-08:00
diff --git a/pages/spicedb/concepts/zanzibar.mdx b/pages/spicedb/concepts/zanzibar.mdx
@@ -5,12 +5,17 @@ import { Callout } from 'nextra/components'
 
 # Google Zanzibar
 
-Zanzibar is the internal authorization system at Google.
+SpiceDB is based on Google Zanzibar, a revolutionary authorization system developed by Google to handle the massive scale and complexity of their services.
 
-A [research paper] publicly documenting the system was published at [2019 USENIX Annual Technical Conference][usenix].
+You may recognize the system if you've ever shared access with another user to a Google product like Google Docs or Gmail.
+
+It's designed to provide consistent, secure, and reliable authorization decisions across Google's vast network of applications and users.
+
+A [research paper] publicly documenting the system was published at [2019 USENIX Annual Technical Conference][usenix]. You can check out our [annotated version], which describes the concepts behind its design and implementation.
 
 [research paper]: https://authzed.com/zanzibar
 [usenix]: https://www.usenix.org/conference/atc19
+[annotated version]: https://authzed.com/zanzibar
 
 ## History
 
@@ -89,12 +94,22 @@ On June 28th 2021, Zanzibar was presented to the [Papers We Love] New York City
 
 ## Differences with SpiceDB
 
-<Callout type="info">
-  The Annotated Zanzibar paper has multiple sets of annotations!
+SpiceDB attempts to remain true to Zanzibar's design principles, but without any assumptions around Google's internal infrastructure and use cases.
+As a result, many things in SpiceDB are more flexible to accommodate different kinds of users with different software stacks.
+For example, [modeling complex user systems][model-users] is possible in SpiceDB, but in Zanzibar all users must be a uint64 identifier.
+
+Because SpiceDB is not forced on developers as company-wide requirement, the project also values developer experience and making the tooling pleasant to work with.
+You can see this in our [Schema Language] and [Playground] which vastly improves the user experience of directly manipulating Protocol Buffers at Google.
 
-  You can read it with [annotations highlighting the differences between SpiceDB and Zanzibar][paper-diff], too!
+[model-users]: ../modeling/representing-users
+[Schema Language]: ../concepts/schema
+[Playground]: https://play.authzed.com
+[z-diff]: ../concepts/zanzibar#differences-with-spicedb
 
-  [paper-diff]: https://authzed.com/zanzibar/#annotations/spicedb
+<Callout type="info">
+    The [Annotated Zanzibar paper] highlights the differences between SpiceDB and Zanzibar!
+
+    [Annotated Zanzibar paper]: https://authzed.com/zanzibar/#annotations/spicedb
 </Callout>
 
 ### Schema Language
@@ -126,14 +141,21 @@ This disambiguation also allowed SpiceDB to drop the confusing `_this` keyword u
 ### Reverse Indices
 
 Both Zanzibar and [SpiceDB][spicedb-expand] implement a ["Reverse Index Expand" API][expand].
-This API responds with a tree structure that can be awkward for applications to consume, especially when it's ideal to avoid co-mingling permissions logic and application code.
 
-As a result, SpiceDB supports additional APIs to simplify consuming [Reverse Indices] without structure.
-In practice, we find that folks prefer a flattened list of results.
+However, this API responds with a tree structure that can be awkward for applications to consume, especially when it's ideal to avoid co-mingling permissions logic and application code.
+
+As a result, SpiceDB supports additional APIs: the [LookupResources] and [LookupSubjects] APIs, which are designed to answer the following questions, respectively:
+
+- "What are all of the resources this subject can access?"
+- "What are all of the subjects with access to this resource?"
+
+[LookupResources]: https://buf.build/authzed/api/docs/main:authzed.api.v1#authzed.api.v1.PermissionsService.LookupResources
+[LookupSubjects]: https://buf.build/authzed/api/docs/main:authzed.api.v1#authzed.api.v1.PermissionsService.LookupSubjects
+
+These APIs make it easier for consumers, because they return a flattened list of results.
 
 [spicedb-expand]: https://buf.build/authzed/api/docs/main:authzed.api.v1#authzed.api.v1.PermissionsService.ExpandPermissionTree
 [expand]: https://authzed.com/zanzibar/2DaJ2vLfht:0.Tk3KF4i94:4S
-[reverse indices]: ../getting-started/faq#what-is-a-reverse-index
 
 ### Datastores
 
@@ -162,17 +184,17 @@ SpiceDB is a bit more flexible with the character-set allowed for Object IDs.
 
 Object Types follow the following Regular Expression:
 
-```
-^([a-z][a-z0-9_]{1,61}[a-z0-9]\/)*[a-z][a-z0-9_]{1,62}[a-z0-9]$
-```
+    ```
+    ^([a-z][a-z0-9_]{1,61}[a-z0-9]\/)*[a-z][a-z0-9_]{1,62}[a-z0-9]$
+    ```
 
 <ObjectTypeDiagram />
 
 Object IDs follow the following Regular Expression:
 
-```
-^(([a-zA-Z0-9/_|\\\-=+]{1,})|\\*)$
-```
+    ```
+    ^(([a-zA-Z0-9/_|\\\-=+]{1,})|\\*)$
+    ```
 
 <ObjectIDDiagram />
 
@@ -187,22 +209,22 @@ This allows SpiceDB to support more complex user systems and perform more powerf
 
 A simple example is a SpiceDB schema modeling both users and API keys:
 
-```zed
-definition ApiKey {}
-definition User {
-  relation keys: ApiKey
-}
-```
+    ```zed
+    definition ApiKey {}
+    definition User {
+      relation keys: ApiKey
+    }
+    ```
 
 You can now model relations and permissions with either type:
 
-```zed {4}
-definition Post {
-  relation viewer: User
-  ...
-  permission view = viewer + viewer->keys
-}
-```
+    ```zed {4}
+    definition Post {
+      relation viewer: User
+      ...
+      permission view = viewer + viewer->keys
+    }
+    ```
 
 Now developers don't have to implement logic in every app that resolves API Keys because SpiceDB already knows how to resolve them.
 
@@ -221,14 +243,6 @@ Now developers don't have to implement logic in every app that resolves API Keys
 
 ## FAQ
 
-### What is Google Zanzibar?
-
-Google Zanzibar is a revolutionary authorization system developed by Google to handle the massive scale and complexity of their services.
-It's designed to provide consistent, secure, and reliable authorization decisions across Google's vast network of applications and users.
-Google published a paper (check out our [annotated copy](https://zanzibar.tech/)) describing the concepts behind its design and implementation.
-
-You may recognize the system if you’ve ever shared access with another user to a Google product like Google Docs or Gmail.
-
 ### Is Zanzibar the same as ReBAC?
 
 While Zanzibar is closely associated with ReBAC (Relationship-Based Access Control), it's not exactly the same thing.
@@ -238,11 +252,6 @@ Zanzibar uses ReBAC as its underlying authorization model.
 So, you could say that Zanzibar is a ReBAC system, but it's more than that.
 It also encompasses the infrastructure, algorithms, and optimizations that allow it to operate at Google's immense scale.
 
-### How does SpiceDB relate to Google Zanzibar?
-
-SpiceDB is an open source authorization system inspired by Google Zanzibar, designed to provide similar functionality with a focus on being accessible and adaptable to a wider range of use cases.
-It shares Zanzibar's core principles,including relationship-based access control (ReBAC), scalability, performance, and strong consistency.
-
 ## Recommended Reading
 
 - [Annotated Zanzibar Paper](https://authzed.com/zanzibar)
diff --git a/pages/spicedb/getting-started/client-libraries.mdx b/pages/spicedb/getting-started/client-libraries.mdx
@@ -19,12 +19,12 @@ Additionally, there are `example` directories in the client libraries that provi
 ## HTTP Clients
 
 SpiceDB exposes an HTTP API when run with the `--http-enabled` flag.
-While Authzed doesn't officially maintain HTTP client libraries, there are [OpenAPI] docs available [here](../api/http-api).
-and served by a SpiceDB instance running the HTTP server.
-For example:
+While Authzed doesn't officially maintain HTTP client libraries, there are [OpenAPI] docs available [here](../api/http-api) and served by a SpiceDB instance running the HTTP server.
+
+Try it out:
 
 ```sh
-docker run --rm -p 50051:50051 -p 8443:8443 authzed/spicedb serve --http-enabled --grpc-preshared-key <preshared key>
+docker run --rm -p 50051:50051 -p 8443:8443 authzed/spicedb serve --http-enabled --grpc-preshared-key foobar
 
 curl localhost:8443/openapi.json
 ```
diff --git a/pages/spicedb/getting-started/faq.mdx b/pages/spicedb/getting-started/faq.mdx
@@ -43,7 +43,7 @@ Notably, policy engines cannot implement [Reverse Indices].
 However, there are some scenarios where ReBAC systems can benefit from dynamic enforcement.
 For these scenarios, SpiceDB supports [Caveats] as a light-weight form of policy that avoids pitfalls present in many other systems.
 
-[Reverse Indices]: #what-is-a-reverse-index
+[Reverse Indices]: ../faq/reverse-indices
 [caveats]: ../concepts/caveats
 
 ## How can I get involved with SpiceDB?
@@ -56,36 +56,3 @@ If you're looking to contribute code, you can read [CONTRIBUTING.md] in our open
 
 [Discord]: https://authzed.com/discord
 [CONTRIBUTING.md]: https://github.com/authzed/spicedb/blob/main/CONTRIBUTING.md
-
-## Zanzibar Questions
-
-### What is a Reverse Index?
-
->Reverse-index expand answers the question "what does this employee have access to?", which most organizations validate as part of meeting those compliance obligations.
->But, even more critically, organizations use this information to debug access issues and as baseline data to ensure careful data handling.
->
-> — Lea Kissner, Zanzibar Coauthor
-
-In SpiceDB, reverse indices often refer to the [LookupResources] and [LookupSubjects] APIs which are designed to answer the following questions, respectively:
-
-- "What are all of the resources this subject can access?"
-- "What are all of the subjects with access to this resource?"
-
-[LookupResources]: https://buf.build/authzed/api/docs/main:authzed.api.v1#authzed.api.v1.PermissionsService.LookupResources
-[LookupSubjects]: https://buf.build/authzed/api/docs/main:authzed.api.v1#authzed.api.v1.PermissionsService.LookupSubjects
-
-### How does SpiceDB improve on Google's Zanzibar?
-
-At a high-level, SpiceDB attempts to remain true to Zanzibar's design principles, but without any assumptions around Google's internal infrastructure and use cases.
-As a result, many things in SpiceDB are more flexible to accomodate different kinds of users with different software stacks.
-For example, [modeling complex user systems][model-users] is possible in SpiceDB, but in Zanzibar all users must be a uint64 identifier.
-
-Because SpiceDB is not forced on developers as company-wide requirement, the project also values developer experience and making the tooling pleasant to work with.
-You can see this in our [Schema Language] and [Playground] which vastly improves the user experience of directly manipulating Protocol Buffers at Google.
-
-For more specific details, see the documentation on the [Zanzibar][z-diff].
-
-[model-users]: ../modeling/representing-users
-[Schema Language]: ../concepts/schema
-[Playground]: https://play.authzed.com
-[z-diff]: ../concepts/zanzibar#differences-with-spicedb
