Choosing Consistency Mode for SpiceDB Permission Checks

Decision: Select a consistency mode for SpiceDB CheckPermission calls

When your application calls SpiceDB's CheckPermission API to evaluate a permission, you must decide whether the request should reflect the very latest committed transaction (strong consistency) or may read from a replica that could be slightly behind (eventual consistency). This choice affects latency, throughput, and the risk of a temporary false‑negative result shortly after a write.

Supported consistency options

SpiceDB exposes consistency through the Consistency message in the CheckPermission request. The supported values are:

• FULLY_CONSISTENT – strong consistency; reads from the leader and guarantees the check reflects all prior committed writes.
• MINIMIZE_LATENCY – eventual consistency; reads from any available replica (typically a follower) to reduce latency.
• AT_LEAST_AS_FRESH and AT_EXACT_SNAPSHOT – advanced options that let you bound staleness using a ZedToken; they are not covered in this guide.

The default consistency mode when the field is omitted is MINIMIZE_LATENCY (eventual reads).

Options comparison

Consistency mode	Typical latency	Throughput impact	Staleness risk	When to use
FULLY_CONSISTENT	Higher (synchronous read from leader)	Lower under heavy write load	None – reflects latest commit	Security‑critical paths, audit‑required checks, or when a write must be immediately visible
MINIMIZE_LATENCY	Lower (read from follower replicas)	Higher, especially read‑heavy workloads	Possible false‑negative for a short window after a write	Read‑heavy lookups, UI permission filters, non‑critical background jobs

Trade‑offs

• Latency vs. correctness: Strong consistency adds the round‑trip to the leader and waits for the write to be durable, increasing latency. Eventual consistency avoids that wait, reducing latency and boosting throughput.
• Staleness window: After a write, an eventual CheckPermission may return false while the permission is actually granted until the change propagates to the replica you read from. The window depends on replication lag and is typically sub‑second to a few seconds.
• Operational simplicity: Strong consistency requires no special handling in the application; eventual consistency may need retry logic or a read‑your‑writes pattern for critical sections.

Concrete implementation example

The following snippets show how to set the consistency field in a CheckPermission request using grpcurl (language‑agnostic JSON placeholders). Replace the placeholders with your actual values.

# Environment variables (set once per process)
export SPICEDB_GRPC_ADDR="localhost:50051"
export SPICEDB_TOKEN="your‑token‑here"

# Strong consistency check (FULLY_CONSISTENT)
grpcurl -d '{
  "resource": {"objectType": "document", "objectId": "doc123"},
  "permission": "view",
  "subject": {"user": "user42"},
  "consistency": {"fully_consistent": {}}
}' -H "authorization: Bearer $SPICEDB_TOKEN" $SPICEDB_GRPC_ADDR authzed.api.v1.PermissionsService/CheckPermission

# Eventual consistency check (MINIMIZE_LATENCY)
grpcurl -d '{
  "resource": {"objectType": "document", "objectId": "doc123"},
  "permission": "view",
  "subject": {"user": "user42"},
  "consistency": {"minimize_latency": {}}
}' -H "authorization: Bearer $SPICEDB_TOKEN" $SPICEDB_GRPC_ADDR authzed.api.v1.PermissionsService/CheckPermission

Run the commands in a terminal where the grpcurl binary is available and you have network access to the SpiceDB instance. No special privileges are required beyond a valid token with permission to read the schema.

Validation steps

1. Start a local SpiceDB instance (e.g., docker run -p 50051:50051 authenticspice/spicedb:latest).
2. Apply a simple schema that defines a document object with a view permission (use the zed CLI or HTTP API).
3. Write a relation granting the permission: zed write --token $SPICEDB_TOKEN --grpc-addr $SPICEDB_GRPC_ADDR "user:user42#view@document:doc123".
4. Immediately issue an eventual CheckPermission (as shown above) and record the response and latency (use time or grpcurl``s built‑in timing).
5. Issue a strong CheckPermission in the same way and record latency and response.
6. Observe that the eventual CheckPermission may return false while the strong CheckPermission returns true, demonstrating the staleness window. Note that the response does not echo the consistency setting; you confirm the setting was honored by checking the request you sent.
7. Repeat the eventual CheckPermission after a short pause (e.g., 2 seconds); it should now return true as the change has propagated.

Limitations and practical checks

• Eventual consistency can produce false‑negatives; ensure your application can tolerate them or implement a retry with exponential backoff for security‑critical decisions.
• Measuring latency accurately requires isolating network jitter; run multiple iterations and take the median.
• Verify that the Consistency field in your request matches the intended mode (e.g., {"fully_consistent":{}} for strong). There is no echo in the response, so client‑side verification is necessary.
• If you need read‑your‑writes guarantees for a specific user session, consider issuing a strong CheckPermission after a write, or use SpiceDB’s Watch API to track changes.