Skip to main content

Feature Overview

SpiceDB is a database system for managing security-critical permissions checking.

SpiceDB acts as a centralized service that stores authorization data. Once stored, data can be performantly queried to answer questions such as "Does this user have access to this resource?" and "What are all the resources this user has access to?".

When used in production, these queries are performed through the API entrypoint, but SpiceDB offers two additional entrypoints: one for integration tests and one for developer tooling.

API Entrypoint​

The API entrypoint is the primary means of running SpiceDB for production deployments. It can serve its API over gRPC or JSON via HTTP and has configuration for data persistence and various aspects of performance.

Architecture​

The following is a high-level overview of the sofware architecture of a SpiceDB deployment. For more information, read the architecture blog post.

'Architecture of a spicedb deployment'

gRPC API​

The recommended and most supported API server for SpiceDB operates using the gRPC protocol. All official client libraries are designed to use this API because it offers the highest performance, reliability, and configurability.

For more information, see the API Overview.

HTTP API​

Optionally, SpiceDB can also support handling JSON requests over HTTP. This is accomplished by using the gRPC Gateway, which translates requests into gRPC messages and forwards them to the port SpiceDB is configured to use for handling gRPC requests. The API is documented via OpenAPI, but may have breaking changes in the future.

For more information, see the API Overview.

Datastore​

Datastores are the means of configuring the behavior and performance of persisting relationship and schema data.

To understand the trade-offs between various implementations of Datastores, see the Selecting a Datastore guide.

Read-only​

All datastores can be configured to operate in a read-only mode. When API requests that attempt to perform writes are made while in read-only, the API will return an Unavailable status with the reason SERVICE_READ_ONLY.

Hedging​

All datastores support having their requests hedged. If a request to the datastore has taken too long, another request is made to hedge against the first never completing. A configurable quantile value, defaulting to p95, is used to determine whether or not a request is slow. When there are not enough samples to accurately use a quantile, a configured absolute duration is used.

Dispatching​

Dispatching is the primary means of distributing caching across a SpiceDB deployment. By default, dispatching only occurs on a single instance. When configured with a server to listen for dispatch requests and a source of peer discovery, SpiceDB will use consistent hashing to map specific requests to specific instances in the deployment with the ultimate goal of improving cache hit rates.

Dashboard​

The dashboard serves as an internal website for humans operating SpiceDB. It currently includes simple instructions for how to configure zed for the running instance.

Integration Tests Entrypoint​

The integration testing entrypoint runs a modified versions of API service intended for applications to use as a fixture for running tests. Each Bearer Token provided by the client is allocated its own isolated, ephemeral datastore. By generating a unique authentication token for each test, tests can be executed in parallel safely against a single instance of SpiceDB.

GitHub Action​

One of the best ways to consume the integration tests entrypoint is via the SpiceDB GitHub Action.

Devtools Entrypoint​

The devtools entrypoint is currently used to power the Playground. It has the capability to validate schemas with relationships and assertions, using an amount that fits in memory. It can also optionally persist and serve schemas bundled with their relationships and assertions. These bundles can be shared or imported into SpiceDB via zed or using flags for bootstrapping SpiceDB.

Language Server​

In the future, this API will change to support the Language Server Protocol, so that more tools than just the Playground are supported.

All Entrypoints​

Logging​

Every entrypoint to SpiceDB supports configuring structured logging with various formats and log levels.

Metrics​

Every entrypoint to SpiceDB has a configurable HTTP server that serves as both a Prometheus metrics endpoint at /metrics and Go runtime pprof endpoints at /debug/pprof. Available metrics include operational information about the Go runtime and serving metrics for any servers that are enabled.

Tracing​

Every entrypoint that runs an API server is instrumented to support OpenTelemetry for distributed tracing. Currently, only Jaeger is supported, but in the future, SpiceDB will support generic OpenTelemetry Collectors.

Available Integrations​

SpiceDB supports integrations with a variety of backing datastores, identity providers, and tools.

Looking for support with additional integrations? Join the SpiceDB community by filing a GitHub issue or providing a contribution.