Merge branch 'main' into data

jzelinskie · web-flow · commit aabcb149482c · 2025-06-18T15:16:51.000-07:00
diff --git a/components/swagger.tsx b/components/swagger.tsx
@@ -0,0 +1,17 @@
+import dynamic from 'next/dynamic'
+import type { SwaggerUIProps } from 'swagger-ui-react'
+
+const SwaggerUI = dynamic(() => import('swagger-ui-react') as Promise<{ default: React.ComponentType<SwaggerUIProps> }>, { ssr: false })
+
+import 'swagger-ui-react/swagger-ui.css'
+
+export function Swagger(props: {}) {
+    return (<SwaggerUI
+        url="https://raw.githubusercontent.com/authzed/api/refs/heads/main/docs/apidocs.swagger.json"
+        deepLinking={true}
+        supportedSubmitMethods={[]}
+        tryItOutEnabled={false}
+        defaultModelsExpandDepth={-1}
+        defaultModelRendering={'model'}
+    />)
+}
diff --git a/globals.css b/globals.css
@@ -23,3 +23,11 @@ body {
   top: 0;
   left: 0;
 }
+
+.swagger-ui .information-container {
+  display: none;
+}
+
+.swagger-ui .scheme-container {
+  display: none;
+}
diff --git a/package.json b/package.json
@@ -37,6 +37,7 @@
     "react-dom": "^18.3.1",
     "react-youtube": "^10.1.0",
     "sharp": "^0.34.0",
+    "swagger-ui-react": "^5.22.0",
     "tailwind-merge": "^2.4.0"
   },
   "devDependencies": {
@@ -54,5 +55,6 @@
     "tailwindcss": "^3.4.4",
     "typescript": "^4.9.5",
     "yaml-loader": "^0.8.1"
-  }
+  },
+  "packageManager": "pnpm@10.10.0+sha512.d615db246fe70f25dcfea6d8d73dee782ce23e2245e3c4f6f888249fb568149318637dca73c2c5c8ef2a4ca0d5657fb9567188bfab47f566d1ee6ce987815c39"
 }
diff --git a/pages/authzed/api/_meta.json b/pages/authzed/api/_meta.json
@@ -5,9 +5,7 @@
     "newWindow": true
   },
   "http-api": {
-    "title": "HTTP API Reference",
-    "href": "https://www.postman.com/authzed/workspace/spicedb/overview",
-    "newWindow": true
+    "title": "HTTP API Reference"
   },
   "cloud-api": {
     "title": "Cloud API Reference",
diff --git a/pages/authzed/api/http-api.mdx b/pages/authzed/api/http-api.mdx
@@ -0,0 +1,5 @@
+import {Swagger} from "../../../components/swagger";
+
+# HTTP API Documentation
+
+<Swagger />
diff --git a/pages/authzed/concepts/restricted-api-access.mdx b/pages/authzed/concepts/restricted-api-access.mdx
@@ -15,14 +15,16 @@ Those familiar with configuring IAM on the major cloud providers should feel com
 - Roles
 - Policies
 
-## Service Accounts
+## Components
+
+### Service Accounts
 
 Service Accounts represent your unique workloads.
 We recommend creating a Service Account for each application that will access the SpiceDB API.
 
 By default Service Accounts have no access to the SpiceDB API; you must apply a Role to gain access.
 
-## Tokens
+### Tokens
 
 Tokens are long-lived credentials for Service Accounts.
 SpiceDB clients must provide a Token in the Authorization header of an API request to perform actions granted to the Service Account.
@@ -31,7 +33,7 @@ Service Accounts can have an arbitrary number of Tokens.
 
 <Callout type="info">We recommend deploying new Tokens before deprovisioning any old Tokens to avoid downtime.</Callout>
 
-### Token Format
+#### Token Format
 
 <Callout type="warning">The entire contents of a Token is considered secret.</Callout>
 
@@ -62,7 +64,7 @@ The command should output the hash, which can be referenced in your static confi
 
 [static configuration]: #static-configuration
 
-## Roles
+### Roles
 
 Roles define rules for accessing the SpiceDB API.
 Roles are bound to Service Accounts to apply those rules to all API Tokens representing the Service Account.
@@ -89,9 +91,51 @@ The following variables are provided the CEL expression varying based on the req
 [cel]: https://github.com/google/cel-spec
 [cel-lang-spec]: https://github.com/google/cel-spec/blob/81e07d7cf76e7fc89b177bd0fdee8ba6d6604bf5/doc/langdef.md
 
-### Example Rule Expressions
+### Policies
+
+Policies are what bind Roles to a Service Account.
+
+Each policy is composed of a unique identifer for the policy itself, the principal (the target of the role assignment), and any roles being assigned.
+
+## Task-Specific Configuration
+
+### `zed backup`/`zed restore`
+
+To configure a service account for use with `zed backup` and `zed restore`, you'll need the following APIs:
+
+On a Service Account on the **source** PS:
+
+```yaml
+## For backup
+# Exporting relationships
+authzed.api/ExportBulkRelationships
+authzed.api/BulkExportRelationships
+
+# Dumping existing schema
+authzed.api/ReadSchema
+```
+
+On a Service Account on the **destination** PS:
+
+```yaml
+## For restore
+## Put these on the DESTINATION PS
+# Importing relationships
+authzed.api/ImportBulkRelationships
+authzed.api/BulkImportRelationships
+
+# Retrying failed relationships
+authzed.api/WriteRelationships
+
+# Writing new schema
+authzed.api/WriteSchema
+```
+
+## Example Rule CEL Expressions
 
-#### Resource-type Write Limit
+These are some examples of CEL expressions that you might attach to Permissions on a Role.
+
+### Resource-type Write Limit
 
 This CEL expression disables the ability for writes to occur on anything but the provided resource type.
 
@@ -101,15 +145,15 @@ This is useful for limiting an application to only be able to perform writes to
 WriteRelationshipsRequest.updates.all(x, x.relationship.resource.object_type == "resource")
 ```
 
-#### Subject-type Write Limit
+### Subject-type Write Limit
 
 This CEL expression disables the ability for writes to occur on anything but the provided subject type.
 
 ```cel
 WriteRelationshipsRequest.updates.all(x, x.relationship.subject.object.object_type == "user")
 ```
 
-#### Create-only Write Limit
+### Create-only Write Limit
 
 This CEL expression disables the ability for writes to perform updates; they can only create new relationships.
 
@@ -120,15 +164,15 @@ WriteRelationshipsRequest.updates.all(
 )
 ```
 
-#### Resource-type Read Limit
+### Resource-type Read Limit
 
 This CEL expression limits the ReadRelationships API from being able to list anything but the a specific resource type.
 
 ```cel
 ReadRelationshipsRequest.relationship_filter.resource_type == "resource"
 ```
 
-#### Blocking Schema Writes
+### Blocking Schema Writes
 
 This CEL expression prevents any schema writes that contain the substring "blockchain".
 This example could be extended to prevent PII or undesirable patterns from reaching a production schema.
@@ -137,20 +181,14 @@ This example could be extended to prevent PII or undesirable patterns from reach
 !WriteSchemaRequest.schema.contains("blockchain")
 ```
 
-#### Limit Checks to one Permission
+### Limit Checks to one Permission
 
 This CEL expression limits CheckPermissions requests to only be able to check a particular permission.
 
 ```cel
 CheckPermissionRequest.permission == "admin"
 ```
 
-## Policies
-
-Policies are what bind Roles to a Service Account.
-
-Each policy is composed of a unique identifer for the policy itself, the principal (the target of the role assignment), and any roles being assigned.
-
 ## Static Configuration
 
 Enterprise builds of SpiceDB can have their API access configured statically with a YAML configuration file.
diff --git a/pages/spicedb/api/_meta.json b/pages/spicedb/api/_meta.json
@@ -5,7 +5,10 @@
     "newWindow": true
   },
   "http-api": {
-    "title": "HTTP API Reference",
+    "title": "HTTP API Reference"
+  },
+  "postman": {
+    "title": "Postman Collection",
     "href": "https://www.postman.com/authzed/workspace/spicedb/overview",
     "newWindow": true
   }
diff --git a/pages/spicedb/api/http-api.mdx b/pages/spicedb/api/http-api.mdx
@@ -0,0 +1,5 @@
+import {Swagger} from "../../../components/swagger";
+
+# HTTP API Documentation
+
+<Swagger />
diff --git a/pages/spicedb/concepts/datastores.mdx b/pages/spicedb/concepts/datastores.mdx
@@ -4,9 +4,9 @@ import { Callout } from 'nextra/components'
 
 In order to reduce operational complexity, SpiceDB leverages existing, popular systems for persisting data.
 
-AuthzZed has standardized our managed services on CockroachDB, but we give self-hosted users the option to pick the datastore that best suits their operational requirements.
+AuthZed has standardized our managed services on CockroachDB, but we give self-hosted customers the option to pick the datastore that best suits their operational requirements.
 
-- [CockroachDB](#cockroachdb) - Recommended for self-hosted deployments with high throughput and/or multi-region requirements
+- [CockroachDB](#cockroachdb) - Recomended for self hosted deployments with high throughput and/or multi-region requirements
 - [Cloud Spanner](#cloud-spanner) - Recommended for self-hosted Google Cloud deployments
 - [PostgreSQL](#postgresql) - Recommended for self-hosted single-region deployments
 - [MySQL](#mysql) - Not recommended; only use if you cannot use PostgreSQL
diff --git a/pages/spicedb/getting-started/client-libraries.mdx b/pages/spicedb/getting-started/client-libraries.mdx
@@ -19,8 +19,7 @@ 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
-both in [the authzed-go git repo](https://github.com/authzed/authzed-go/blob/main/proto/apidocs.swagger.json)
+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:
 
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
