diff --git a/app/spicedb/concepts/commands/page.mdx b/app/spicedb/concepts/commands/page.mdx index 8fd57da..e41f4eb 100644 --- a/app/spicedb/concepts/commands/page.mdx +++ b/app/spicedb/concepts/commands/page.mdx @@ -27,13 +27,12 @@ A database that stores and computes permissions ### Children commands -- [spicedb datastore](#reference-spicedb-datastore) - datastore operations -- [spicedb lsp](#reference-spicedb-lsp) - serve language server protocol -- [spicedb man](#reference-spicedb-man) - Generate man page -- [spicedb serve](#reference-spicedb-serve) - serve the permissions database -- [spicedb serve-testing](#reference-spicedb-serve-testing) - test server with an in-memory datastore -- [spicedb version](#reference-spicedb-version) - displays the version of SpiceDB - +- [spicedb datastore](#reference-spicedb-datastore) - datastore operations +- [spicedb lsp](#reference-spicedb-lsp) - serve language server protocol +- [spicedb man](#reference-spicedb-man) - Generate man page +- [spicedb serve](#reference-spicedb-serve) - serve the permissions database +- [spicedb serve-testing](#reference-spicedb-serve-testing) - test server with an in-memory datastore +- [spicedb version](#reference-spicedb-version) - displays the version of SpiceDB ## Reference: `spicedb datastore` @@ -49,11 +48,10 @@ Operations against the configured datastore ### Children commands -- [spicedb datastore gc](#reference-spicedb-datastore-gc) - executes garbage collection -- [spicedb datastore head](#reference-spicedb-datastore-head) - compute the head (latest) database migration revision available -- [spicedb datastore migrate](#reference-spicedb-datastore-migrate) - execute datastore schema migrations -- [spicedb datastore repair](#reference-spicedb-datastore-repair) - executes datastore repair - +- [spicedb datastore gc](#reference-spicedb-datastore-gc) - executes garbage collection +- [spicedb datastore head](#reference-spicedb-datastore-head) - compute the head (latest) database migration revision available +- [spicedb datastore migrate](#reference-spicedb-datastore-migrate) - execute datastore schema migrations +- [spicedb datastore repair](#reference-spicedb-datastore-repair) - executes datastore repair ## Reference: `spicedb datastore gc` @@ -148,8 +146,6 @@ spicedb datastore gc [flags] --skip-release-check if true, skips checking for new SpiceDB releases ``` - - ## Reference: `spicedb datastore head` compute the head (latest) database migration revision available @@ -181,8 +177,6 @@ spicedb datastore head [flags] --skip-release-check if true, skips checking for new SpiceDB releases ``` - - ## Reference: `spicedb datastore migrate` Executes datastore schema migrations for the datastore. @@ -222,8 +216,6 @@ spicedb datastore migrate [revision] [flags] --skip-release-check if true, skips checking for new SpiceDB releases ``` - - ## Reference: `spicedb datastore repair` Executes a repair operation for the datastore @@ -317,8 +309,6 @@ spicedb datastore repair [flags] --skip-release-check if true, skips checking for new SpiceDB releases ``` - - ## Reference: `spicedb lsp` serve language server protocol @@ -342,12 +332,10 @@ spicedb lsp [flags] --skip-release-check if true, skips checking for new SpiceDB releases ``` - - ## Reference: `spicedb man` Generate a man page for SpiceDB. - The output can be redirected to a file and installed to the system: +The output can be redirected to a file and installed to the system: ``` spicedb man > spicedb.1 @@ -355,7 +343,6 @@ Generate a man page for SpiceDB. sudo mandb # Update man page database ``` - ``` spicedb man ``` @@ -368,8 +355,6 @@ spicedb man --skip-release-check if true, skips checking for new SpiceDB releases ``` - - ## Reference: `spicedb serve` start a SpiceDB server @@ -558,8 +543,6 @@ spicedb serve [flags] --skip-release-check if true, skips checking for new SpiceDB releases ``` - - ## Reference: `spicedb serve-testing` An in-memory spicedb server which serves completely isolated datastores per client-supplied auth token used. @@ -621,8 +604,6 @@ spicedb serve-testing [flags] --skip-release-check if true, skips checking for new SpiceDB releases ``` - - ## Reference: `spicedb version` displays the version of SpiceDB @@ -644,6 +625,3 @@ spicedb version [flags] --log-level string verbosity of logging ("trace", "debug", "info", "warn", "error") (default "info") --skip-release-check if true, skips checking for new SpiceDB releases ``` - - - diff --git a/app/spicedb/getting-started/client-libraries/page.mdx b/app/spicedb/getting-started/client-libraries/page.mdx index eb804d6..1898de9 100644 --- a/app/spicedb/getting-started/client-libraries/page.mdx +++ b/app/spicedb/getting-started/client-libraries/page.mdx @@ -1,3 +1,5 @@ +import { Tabs } from "nextra/components"; + # Official Client Libraries SpiceDB is primarily accessed by a [gRPC] API and thus client libraries can be generated for any programming language. @@ -9,13 +11,55 @@ AuthZed builds and maintains gRPC client libraries for the following languages: - [Python](https://github.com/authzed/authzed-py) - [Ruby](https://github.com/authzed/authzed-rb) - [Java](https://github.com/authzed/authzed-java) -- [Dotnet](https://github.com/authzed/authzed-dotnet) +- [.NET](https://github.com/authzed/authzed-dotnet) Because the above libraries are generated from protobuf definitions in our [API repo], the primary documentation for the gRPC API is in the [buf documentation] for SpiceDB's services. The gRPC client documentation associated with each host language will also be helpful for putting together invocations. Additionally, there are `example` directories in the client libraries that provide example usages. +## Local Development + +When developing locally, you'll need to configure your client based on how SpiceDB is running. + +### SpiceDB running without TLS (most common) + +If SpiceDB is started without TLS (using `--grpc-no-tls`), use insecure plaintext credentials: + + + `v1.ClientSecurity.INSECURE_PLAINTEXT_CREDENTIALS` + + `grpcutil.WithInsecureBearerToken()` and + `grpc.WithTransportCredentials(insecure.NewCredentials())` + + `insecure_bearer_token_credentials()` + `credentials: :this_channel_is_insecure` + `.usePlaintext()` + + `ChannelCredentials.Insecure` with `UnsafeUseInsecureChannelCallCredentials + = true` (also requires + `AppContext.SetSwitch("System.Net.Http.SocketsHttpHandler.Http2UnencryptedSupport", + true)`) + + + +This applies to localhost, Docker, OrbStack, and other local environments running without TLS. + +### SpiceDB running with TLS using self-signed certificates + +If SpiceDB is running with TLS but using a self-signed or untrusted certificate: + + + + `v1.ClientSecurity.INSECURE_LOCALHOST_ALLOWED` (allows localhost connections without CA verification) + + + Load the self-signed CA explicitly with `grpcutil.WithCustomCerts()` or use `grpc.WithTransportCredentials(credentials.NewTLS(&tls.Config{InsecureSkipVerify: true}))` for localhost only (not recommended for production) + + + +See the [Protecting a Blog Application](./protecting-a-blog#checking-permissions) tutorial for examples. + ## HTTP Clients SpiceDB exposes an HTTP API when run with the `--http-enabled` flag. diff --git a/app/spicedb/getting-started/installing-zed/page.mdx b/app/spicedb/getting-started/installing-zed/page.mdx index f3e00d0..72d0a89 100644 --- a/app/spicedb/getting-started/installing-zed/page.mdx +++ b/app/spicedb/getting-started/installing-zed/page.mdx @@ -1,4 +1,4 @@ -import { Callout } from 'nextra/components' +import { Callout } from "nextra/components"; # Installing Zed @@ -123,7 +123,6 @@ You can find more commands for tasks such as testing, linting in the repository' [CONTRIBUTING.md]: https://github.com/authzed/zed/blob/main/CONTRIBUTING.md - ## Reference: `zed` A command-line client for managing SpiceDB clusters. @@ -161,17 +160,16 @@ zed permission check --explain document:firstdoc writer user:emilia ### Children commands -- [zed backup](#reference-zed-backup) - Create, restore, and inspect permissions system backups -- [zed context](#reference-zed-context) - Manage configurations for connecting to SpiceDB deployments -- [zed import](#reference-zed-import) - Imports schema and relationships from a file or url -- [zed mcp](#reference-zed-mcp) - MCP (Model Context Protocol) server commands -- [zed permission](#reference-zed-permission) - Query the permissions in a permissions system -- [zed relationship](#reference-zed-relationship) - Query and mutate the relationships in a permissions system -- [zed schema](#reference-zed-schema) - Manage schema for a permissions system -- [zed use](#reference-zed-use) - Alias for `zed context use` -- [zed validate](#reference-zed-validate) - Validates the given validation file (.yaml, .zaml) or schema file (.zed) -- [zed version](#reference-zed-version) - Display zed and SpiceDB version information - +- [zed backup](#reference-zed-backup) - Create, restore, and inspect permissions system backups +- [zed context](#reference-zed-context) - Manage configurations for connecting to SpiceDB deployments +- [zed import](#reference-zed-import) - Imports schema and relationships from a file or url +- [zed mcp](#reference-zed-mcp) - MCP (Model Context Protocol) server commands +- [zed permission](#reference-zed-permission) - Query the permissions in a permissions system +- [zed relationship](#reference-zed-relationship) - Query and mutate the relationships in a permissions system +- [zed schema](#reference-zed-schema) - Manage schema for a permissions system +- [zed use](#reference-zed-use) - Alias for `zed context use` +- [zed validate](#reference-zed-validate) - Validates the given validation file (.yaml, .zaml) or schema file (.zed) +- [zed version](#reference-zed-version) - Display zed and SpiceDB version information ## Reference: `zed backup` @@ -210,13 +208,12 @@ zed backup [flags] ### Children commands -- [zed backup create](#reference-zed-backup-create) - Backup a permission system to a file -- [zed backup parse-relationships](#reference-zed-backup-parse-relationships) - Extract the relationships from a backup file -- [zed backup parse-revision](#reference-zed-backup-parse-revision) - Extract the revision from a backup file -- [zed backup parse-schema](#reference-zed-backup-parse-schema) - Extract the schema from a backup file -- [zed backup redact](#reference-zed-backup-redact) - Redact a backup file to remove sensitive information -- [zed backup restore](#reference-zed-backup-restore) - Restore a permission system from a file - +- [zed backup create](#reference-zed-backup-create) - Backup a permission system to a file +- [zed backup parse-relationships](#reference-zed-backup-parse-relationships) - Extract the relationships from a backup file +- [zed backup parse-revision](#reference-zed-backup-parse-revision) - Extract the revision from a backup file +- [zed backup parse-schema](#reference-zed-backup-parse-schema) - Extract the schema from a backup file +- [zed backup redact](#reference-zed-backup-redact) - Redact a backup file to remove sensitive information +- [zed backup restore](#reference-zed-backup-restore) - Restore a permission system from a file ## Reference: `zed backup create` @@ -253,8 +250,6 @@ zed backup create [flags] --token string token used to authenticate to SpiceDB ``` - - ## Reference: `zed backup parse-relationships` Extract the relationships from a backup file @@ -288,8 +283,6 @@ zed backup parse-relationships [flags] --token string token used to authenticate to SpiceDB ``` - - ## Reference: `zed backup parse-revision` Extract the revision from a backup file @@ -317,8 +310,6 @@ zed backup parse-revision --token string token used to authenticate to SpiceDB ``` - - ## Reference: `zed backup parse-schema` Extract the schema from a backup file @@ -353,8 +344,6 @@ zed backup parse-schema [flags] --token string token used to authenticate to SpiceDB ``` - - ## Reference: `zed backup redact` Redact a backup file to remove sensitive information @@ -391,8 +380,6 @@ zed backup redact [flags] --token string token used to authenticate to SpiceDB ``` - - ## Reference: `zed backup restore` Restore a permission system from a file @@ -432,8 +419,6 @@ zed backup restore [flags] --token string token used to authenticate to SpiceDB ``` - - ## Reference: `zed context` Manage configurations for connecting to SpiceDB deployments @@ -459,11 +444,10 @@ Manage configurations for connecting to SpiceDB deployments ### Children commands -- [zed context list](#reference-zed-context-list) - Lists all available contexts -- [zed context remove](#reference-zed-context-remove) - Removes a context by name -- [zed context set](#reference-zed-context-set) - Creates or overwrite a context -- [zed context use](#reference-zed-context-use) - Sets a context as the current context - +- [zed context list](#reference-zed-context-list) - Lists all available contexts +- [zed context remove](#reference-zed-context-remove) - Removes a context by name +- [zed context set](#reference-zed-context-set) - Creates or overwrite a context +- [zed context use](#reference-zed-context-use) - Sets a context as the current context ## Reference: `zed context list` @@ -498,8 +482,6 @@ zed context list [flags] --token string token used to authenticate to SpiceDB ``` - - ## Reference: `zed context remove` Removes a context by name @@ -527,8 +509,6 @@ zed context remove --token string token used to authenticate to SpiceDB ``` - - ## Reference: `zed context set` Creates or overwrite a context @@ -556,8 +536,6 @@ zed context set --token string token used to authenticate to SpiceDB ``` - - ## Reference: `zed context use` Sets a context as the current context @@ -585,8 +563,6 @@ zed context use --token string token used to authenticate to SpiceDB ``` - - ## Reference: `zed import` Imports schema and relationships from a file or url @@ -657,8 +633,6 @@ zed import [flags] --token string token used to authenticate to SpiceDB ``` - - ## Reference: `zed mcp` MCP (Model Context Protocol) server commands. @@ -688,8 +662,7 @@ To use with Claude Code, run `zed mcp experimental-run` to start the SpiceDB Dev ### Children commands -- [zed mcp experimental-run](#reference-zed-mcp-experimental-run) - Run the Experimental MCP server - +- [zed mcp experimental-run](#reference-zed-mcp-experimental-run) - Run the Experimental MCP server ## Reference: `zed mcp experimental-run` @@ -724,8 +697,6 @@ zed mcp experimental-run [flags] --token string token used to authenticate to SpiceDB ``` - - ## Reference: `zed permission` Query the permissions in a permissions system @@ -751,12 +722,11 @@ Query the permissions in a permissions system ### Children commands -- [zed permission bulk](#reference-zed-permission-bulk) - Check permissions in bulk exist for resource-permission-subject triplets -- [zed permission check](#reference-zed-permission-check) - Check if a subject has permission on a resource -- [zed permission expand](#reference-zed-permission-expand) - Expand the structure of a permission -- [zed permission lookup-resources](#reference-zed-permission-lookup-resources) - Enumerates the resources of a given type for which a subject has permission -- [zed permission lookup-subjects](#reference-zed-permission-lookup-subjects) - Enumerates the subjects of a given type for which the subject has permission on the resource - +- [zed permission bulk](#reference-zed-permission-bulk) - Check permissions in bulk exist for resource-permission-subject triplets +- [zed permission check](#reference-zed-permission-check) - Check if a subject has permission on a resource +- [zed permission expand](#reference-zed-permission-expand) - Expand the structure of a permission +- [zed permission lookup-resources](#reference-zed-permission-lookup-resources) - Enumerates the resources of a given type for which a subject has permission +- [zed permission lookup-subjects](#reference-zed-permission-lookup-subjects) - Enumerates the subjects of a given type for which the subject has permission on the resource ## Reference: `zed permission bulk` @@ -798,8 +768,6 @@ zed permission bulk [flags] --token string token used to authenticate to SpiceDB ``` - - ## Reference: `zed permission expand` Expand the structure of a permission @@ -881,8 +847,6 @@ zed permission expand [flags] --token string token used to authenticate to SpiceDB ``` - - ## Reference: `zed permission lookup-resources` Enumerates the resources of a given type for which a subject has permission @@ -925,8 +889,6 @@ zed permission lookup-resources [flags] --token string token used to authenticate to SpiceDB ``` - - ## Reference: `zed permission lookup-subjects` Enumerates the subjects of a given type for which the subject has permission on the resource @@ -966,8 +928,6 @@ zed permission lookup-subjects [flags] zed preview schema compile root.zed Write to an output file: zed preview schema compile root.zed --out compiled.zed - + ``` ### Options @@ -1012,8 +972,6 @@ zed preview schema compile [flags] --token string token used to authenticate to SpiceDB ``` - - ## Reference: `zed relationship` Query and mutate the relationships in a permissions system @@ -1039,13 +997,12 @@ Query and mutate the relationships in a permissions system ### Children commands -- [zed relationship bulk-delete](#reference-zed-relationship-bulk-delete) - Deletes relationships matching the provided pattern en masse -- [zed relationship create](#reference-zed-relationship-create) - Create a relationship for a subject -- [zed relationship delete](#reference-zed-relationship-delete) - Deletes a relationship -- [zed relationship read](#reference-zed-relationship-read) - Enumerates relationships matching the provided pattern -- [zed relationship touch](#reference-zed-relationship-touch) - Idempotently updates a relationship for a subject -- [zed relationship watch](#reference-zed-relationship-watch) - Watches the stream of relationship updates and schema updates from the server - +- [zed relationship bulk-delete](#reference-zed-relationship-bulk-delete) - Deletes relationships matching the provided pattern en masse +- [zed relationship create](#reference-zed-relationship-create) - Create a relationship for a subject +- [zed relationship delete](#reference-zed-relationship-delete) - Deletes a relationship +- [zed relationship read](#reference-zed-relationship-read) - Enumerates relationships matching the provided pattern +- [zed relationship touch](#reference-zed-relationship-touch) - Idempotently updates a relationship for a subject +- [zed relationship watch](#reference-zed-relationship-watch) - Watches the stream of relationship updates and schema updates from the server ## Reference: `zed relationship bulk-delete` @@ -1082,8 +1039,6 @@ zed relationship bulk-delete < --token string token used to authenticate to SpiceDB ``` - - ## Reference: `zed relationship touch` Idempotently updates a relationship for a subject @@ -1262,8 +1211,6 @@ zed relationship touch [flags] --token string token used to authenticate to SpiceDB ``` - - ## Reference: `zed schema diff` Diff two schema files @@ -1407,8 +1349,6 @@ zed schema diff --token string token used to authenticate to SpiceDB ``` - - ## Reference: `zed schema read` Read the schema of a permissions system @@ -1442,8 +1382,6 @@ zed schema read [flags] --token string token used to authenticate to SpiceDB ``` - - ## Reference: `zed schema write` Write a schema file (.zed or stdin) to the current permissions system @@ -1489,8 +1427,6 @@ zed schema write [flags] --token string token used to authenticate to SpiceDB ``` - - ## Reference: `zed use` Alias for `zed context use` @@ -1518,8 +1454,6 @@ zed use --token string token used to authenticate to SpiceDB ``` - - ## Reference: `zed validate` Validates the given validation file (.yaml, .zaml) or schema file (.zed) @@ -1578,8 +1512,6 @@ zed validate [flags] --token string token used to authenticate to SpiceDB ``` - - ## Reference: `zed version` Display zed and SpiceDB version information @@ -1613,6 +1545,3 @@ zed version [flags] --skip-version-check if true, no version check is performed against the server --token string token used to authenticate to SpiceDB ``` - - - diff --git a/app/spicedb/getting-started/protecting-a-blog/page.mdx b/app/spicedb/getting-started/protecting-a-blog/page.mdx index 8fa18b1..14ccc5c 100644 --- a/app/spicedb/getting-started/protecting-a-blog/page.mdx +++ b/app/spicedb/getting-started/protecting-a-blog/page.mdx @@ -647,6 +647,13 @@ For example, in our example schema, writers have both write and read permissions Let's perform some permission checks: + + If developing locally against SpiceDB, see + [this](./client-libraries#local-development) for full details on how to setup + credentials. Always switch to secure credentials before launching to + production. + + @@ -665,8 +672,8 @@ import { v1 } from "@authzed/authzed-node"; const { promises: client } = v1.NewClient( "t_your_token_here_1234567deadbeef", - "grpc.authzed.com:50051", - // NOTE: Remove if SpiceDB is behind TLS + "localhost:50051", + // For local development without TLS (remove for AuthZed Cloud) v1.ClientSecurity.INSECURE_PLAINTEXT_CREDENTIALS, ); diff --git a/app/spicedb/ops/data/bulk-operations/page.mdx b/app/spicedb/ops/data/bulk-operations/page.mdx index 99ea8ab..5225a78 100644 --- a/app/spicedb/ops/data/bulk-operations/page.mdx +++ b/app/spicedb/ops/data/bulk-operations/page.mdx @@ -24,7 +24,7 @@ We'll use the [authzed-dotnet](https://github.com/authzed/authzed-dotnet) client Other client libraries will have different syntax and structures around their streaming and iteration, but this should demonstrate the two different levels of chunking that we'll do in the process. - + ```csharp var TOTAL_RELATIONSHIPS_TO_WRITE = 1000;