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 t