SpiceDB sets the standard for authorization that scales.

Scale with
Traffic • Dev Velocity • Functionality • Geography

         

   

 

What is SpiceDB?

SpiceDB is the most mature open source project inspired by Google's internal authorization system: Zanzibar.

As of 2021, broken access control became the #1 threat to web security according to OWASP. With SpiceDB, platform and product teams can be be protected by answering this question easily: "can subject X perform action Y on resource Z?"

Similar to a relational database, developers define a schema, write data in the form of relationships, and then use SpiceDB's clients to issue permission checks in their application to determine what actions a user can take on a resource. Other queries are also possible, such as "What can subject do?" or "Who can access resource?".

SpiceDB is often ran as a centralized service shared across product suites and microservice architectures.

SpiceDB is focused purely on authorization and is designed to be fully agnostic to authentication solutions/identity providers.

What is Google Zanzibar?

In 2019, Google released the paper "Zanzibar: Google's Consistent, Global Authorization System" providing the original inspiration for SpiceDB. The paper presents the design, implementation, and deployment of, Zanzibar, Google's internal system for storing and evaluating access control lists. Originally designed for Google+ Circles, Zanzibar now sits at the core Google's entire product suite (Calendar, Drive, Maps, Photos, YouTube) and powers the Google Cloud IAM service.

While SpiceDB has gone on to innovate well beyond the functionality outlined in the paper, development of SpiceDB aims to always remain faithful to the paper's values and goals.

Why SpiceDB?

• World-class engineering: painstakingly built by experts that pioneered the cloud-native ecosystem
• Authentic design: mature and feature-complete implementation of Google's Zanzibar paper
• Proven in production: 5ms p95 when scaled to millions of queries/s, billions of relationships
• Global consistency: consistency configured per-request unlocks correctness while maintaining performance
• Multi-paradigm: caveated relationships combine the best concepts in authorization: ABAC & ReBAC
• Safety in tooling: designs schemas with real-time validation or validate in your CI/CD workflow
• Reverse Indexes: queries for "What can subject do?", "Who can access resource?"

Who uses SpiceDB?

SpiceDB is a powerful tool in a variety of domains and in organizations of all sizes; we've chosen to highlight a few interesting community members:

• IBM's AI Data & Model Factory Platform
• Red Hat's Insights Platform
• GitPod
• TubiTV China (中文)
• DMM Online Salon (日本語)

Beyond the community, you can also read customer stories for commercial usage of SpiceDB.

Getting Started

Installing the binary

Binary releases are available for Linux, macOS, and Windows on AMD64 and ARM64 architectures.

Homebrew users for both macOS and Linux can install the latest binary releases of SpiceDB and zed using the official tap:

brew install authzed/tap/spicedb authzed/tap/zed

Debian-based Linux users can install SpiceDB packages by adding a new APT source:

sudo apt update && sudo apt install -y curl ca-certificates gpg
curl https://pkg.authzed.com/apt/gpg.key | sudo apt-key add -
sudo echo "deb https://pkg.authzed.com/apt/ * *" > /etc/apt/sources.list.d/fury.list
sudo apt update && sudo apt install -y spicedb zed

RPM-based Linux users can install SpiceDB packages by adding a new YUM repository:

sudo cat << EOF >> /etc/yum.repos.d/Authzed-Fury.repo
[authzed-fury]
name=AuthZed Fury Repository
baseurl=https://pkg.authzed.com/yum/
enabled=1
gpgcheck=0
EOF
sudo dnf install -y spicedb zed

Running a container

Container images are available for AMD64 and ARM64 architectures on the following registries:

• authzed/spicedb
• ghcr.io/authzed/spicedb
• quay.io/authzed/spicedb

Docker users can run the latest SpiceDB container with the following:

# expose grpc and http. http is used in the examples below.
docker run --rm -p 50051:50051 -p 8443:8443 authzed/spicedb serve --http-enabled true --grpc-preshared-key "somerandomkeyhere"

SpiceDB containers use Chainguard Images to ship the bare minimum userspace which is a huge boon to security, but can complicate debugging. If you want to execute a user session into a running SpiceDB container and install packages, you can use one of our debug images.

Appending -debug to any tag will provide you an image that has a userspace with debug tooling:

docker run --rm -ti --entrypoint sh authzed/spicedb:latest-debug

Containers are also available for each git commit to the main branch under ${REGISTRY}/authzed/spicedb-git:${COMMIT}.

Write your own schema and relationships

Now that you have SpiceDB running, you must define your schema and write relationships that represent the permissions in your application. There are various way to do this:

• Use the client libraries.
• Use the hosted Playground or run it yourself locally. The playground contains a set of example schemas and test data for different scenarios.
• Use the zed CLI.
• Use the gRPC or the HTTP APIs. For example:

    # write a schema
    curl --location 'http://localhost:8443/v1/schema/write' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer somerandomkeyhere' \
    --data '{
        "schema": "definition user {} \n definition folder { \n relation parent: folder\n relation viewer: user \n permission view = viewer + parent->view \n } \n definition document {\n relation folder: folder \n relation viewer: user \n permission view = viewer + folder->view \n }"
    }'

    # write a relationship
    curl --location 'http://localhost:8443/v1/relationships/write' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer somerandomkeyhere' \
    --data '{
        "updates": [
            {
                "operation": "OPERATION_TOUCH",
                "relationship": {
                    "resource": {
                        "objectType": "folder",
                        "objectId": "budget"
                    },
                    "relation": "viewer",
                    "subject": {
                        "object": {
                            "objectType": "user",
                            "objectId": "anne"
                        }
                    }
                }
            }
        ]
    }'

You can follow a guide for developing a schema or review the the schema language design documentation.

Finally, you can watch the SpiceDB primer video on schema development.

Query the SpiceDB API

You can use the client libraries or the gRPC and HTTP APIs to query SpiceDB. For example,

curl --location 'http://localhost:8443/v1/permissions/check' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer somerandomkeyhere' \
--data '{
  "consistency": {
    "minimizeLatency": true
  },
  "resource": {
    "objectType": "folder",
    "objectId": "budget"
  },
  "permission": "view",
  "subject": {
    "object": {
      "objectType": "user",
      "objectId": "anne"
    }
  }
}'


#{
#    "checkedAt": {
#        "token": "GhUKEzE3NTE1NjYwMjUwMDAwMDAwMDA="
#    },
#    "permissionship": "PERMISSIONSHIP_HAS_PERMISSION"
#}

'

You can also issue queries with zed, the official command-line client. The Playground also has a tab for experimenting with zed all from within your browser.

Integrating SpiceDB into Your Application

To get an understanding of integrating an application with SpiceDB, you can follow the Protecting Your First App guide or review API documentation on the Buf Registry or Postman.

Deploying to Production

The core SpiceDB service has been utilized in production by Authzed since 2021 so you can be confident that it is battle-tested. Moreover, it supports various datastores, including Google Cloud Spanner, CockroachDB, MySQL, and PostgreSQL. Read this to learn the best practices for each.

You can choose to self-host SpiceDB, or use AuthZed Cloud, a fully managed service. See a comparison of the various options.

If you choose to self-host, we recommend deploying SpiceDB using Kubernetes. If you're only experimenting, feel free to try out one of our community-maintained examples for testing SpiceDB on Kubernetes:

kubectl apply -f https://raw.githubusercontent.com/authzed/examples/main/kubernetes/example.yaml

For a more detailed guide on the SpiceDB Kubernetes Operator, see this.

For more best practices on deploying SpiceDB, read our best practices guide.

Telemetry

SpiceDB collects anonymous telemetry data to help us understand how the community is using SpiceDB and to help us prioritize features. This telemetry is opt-out and can be disabled via setting --telemetry-endpoint="". For more information on the telemetry we collect, see telemetry.

More Resources

• Ask questions via GitHub Discussions or our Community Discord
• Read blog posts from the Authzed team describing the project and major announcements
• Watch our YouTube videos about SpiceDB, modeling schemas, leveraging CNCF projects, and more
• Explore the SpiceDB Awesome List that enumerates official and third-party projects built by the community
• Reference community examples for demo environments, integration testing, CI pipelines, and writing schemas

Join the Community

Join our fellow contributors from companies such as GitHub, Adobe, Google, Fastly, Plaid, Red Hat, and Reddit.

SpiceDB is a community project where everyone is invited to participate and feel welcomed. While the project has a technical goal, participation is not restricted to those with code contributions.

CONTRIBUTING.md documents communication, contribution flow, legal requirements, and common tasks when contributing to the project.

You can find issues by priority: Urgent, High, Medium, Low, Maybe. There are also good first issues.

Our documentation is also open source if you'd like to clarify anything you find confusing.

Acknowledgements

SpiceDB is a community project fueled by contributions from both organizations and individuals. We appreciate all contributions, large and small, and would like to thank all those involved.

In addition, we'd like to highlight a few notable contributions:

• The GitHub Authorization Team for implementing and contributing the MySQL datastore
• The Netflix Authorization Team for sponsoring and being a design partner for caveats
• The Equinix Metal Team for sponsoring our benchmarking hardware