If you run a Zanzibar-style relationship-based access control (ReBAC) engine, SpiceDB in the examples here, and you are moving authorization to Cerbos, this guide walks through the whole move. If you are doing the work, you get a full schema translated to policy with passing tests, the calls that replace CheckPermission and LookupResources, and a plan for running Cerbos beside SpiceDB before it enforces anything. If you are approving it, you get what changes for each team and how risk is controlled at each step.
Your permission rules stay the same. Owners still edit, folder viewers still see what is in the folder, banned users are still kept out. What changes is where the facts behind those rules live, and what your team has to run to keep them current.
Why migrating from SpiceDB to Cerbos is mostly a data question
A Zanzibar-style engine holds a copy of every relationship as a tuple, and your application writes a tuple every time a matching fact changes in its own database. That copy is the source of most of the work around the engine. The dual write between your database and the tuple store is a known hard problem, and the usual fixes, an outbox table, change data capture, periodic consistency checks, or making the engine the only source of truth, each add a system of their own.
Cerbos evaluates policy against data where it already lives, so the migration is mostly deciding, for each kind of tuple, where that fact comes from afterwards. Usually it is a column your database already has, because the tuple was a copy of it. Sometimes it is a group in your identity provider, and sometimes a lookup that Cerbos Synapse makes at decision time. Translating the schema is the smaller job, because SpiceDB relations and permissions map onto derived roles, rules and conditions, and SpiceDB caveats are already written in CEL, the language Cerbos conditions use.
For a CTO, the outcome is one less stateful system to run and one less write path in every feature. For an identity team, joiners, movers and leavers reach authorization from the directory they already govern, within the cache time they set, with no tuples to update or delete. For a security team, every decision is logged with the policy that made it.
What replaces SpiceDB and its datastore after you migrate
The engine, its datastore, the sync pipeline and the consistency tokens go. In their place is one authorization platform, deployed where you need it.
-
Decisions run in Cerbos PDP, a stateless decision point next to each workload, as a sidecar, a shared service or embedded at the edge. It holds policy only, so there is no CockroachDB, Spanner or Postgres cluster behind it.
-
Policy lives in Git or in Cerbos Hub policy stores. Cerbos Hub runs your tests on every change, distributes the policy to every decision point, shows which version each one runs and rolls back in one step.
-
Data stays in your database and identity provider. Cerbos Synapse fetches what the application does not send, with cache times set per source.
-
Audit comes from decision logs that Cerbos Hub collects from every decision point, each one tied to the policy version that made it.
Key Cerbos principles to know before translating a SpiceDB schema
Policies are per resource kind. A SpiceDB definition with its permissions becomes a resource policy for that kind, such as document. Relationships between a person and a resource become derived roles, named roles granted when a condition is true.
Everything is denied unless a rule allows it, and an explicit deny beats any allow. That is how SpiceDB's exclusion operator carries across.
Conditions are CEL. Comparisons, list membership, timestamps with now() and IP ranges with inIPAddrRange are built in, and the conditions reference lists the rest.
A check gets facts, not a graph. A chain such as a document inheriting viewers from every ancestor folder is resolved before the check, by the application or by Cerbos Synapse querying the folder tree, and arrives as an attribute such as "the folders this person can view".
Policies come with tests. Each policy has a test suite that runs in CI and in Cerbos Hub before anything deploys.
SpiceDB to Cerbos concept mapping
| SpiceDB | Cerbos | Notes |
|---|---|---|
definition document |
A resource policy for document |
One policy file per resource kind |
relation owner: user |
Derived role owner, condition R.attr.owner == P.id |
The owner is a column you already store |
relation viewer: user | group#member |
Derived role with P.id in R.attr.viewers, and group grants checked against P.attr.groups |
Groups come from the identity provider token or Cerbos Synapse |
permission edit = owner + editor (union) |
One rule listing several derived roles | Any listed role allows the action |
& intersection, .all() |
all: in a condition, or CEL's all() macro over a list |
|
- exclusion |
A separate EFFECT_DENY rule |
Deny always wins |
parent->view, .any() arrows |
An attribute resolved before the check, such as P.attr.viewableFolders |
The application or Cerbos Synapse walks the tree |
user:* wildcard |
A boolean such as R.attr.public |
Explicit, and easy to audit |
Caveat with with |
A CEL condition on the rule or derived role | Caveat parameters become request attributes |
| Expiring relationship | A timestamp attribute checked with now() |
|
| CheckPermission, CheckBulkPermissions | CheckResources | One call checks many actions on many resources |
| LookupResources | PlanResources, a query plan your database runs | |
| LookupSubjects | A query on your own sharing and membership tables | Your own tables already answer who has access |
| WriteRelationships, DeleteRelationships | Nothing. Write to your own database as usual | The dual write disappears |
| ZedToken, consistency modes | Not needed. Facts are read from the source, with cache times you set per source | |
| Watch | Not needed for authorization | Keep it only for consumers that are not about authorization |
zed validate, assertions |
cerbos compile and policy test suites |
A worked example of translating a SpiceDB schema to Cerbos
Here is a typical document and folder schema in SpiceDB. Documents sit in folders, folders inherit viewers from parent folders and organization admins, editors must connect from the corporate network, some documents are public, guests get expiring access and banned users are excluded from viewing.
use expiration
caveat ip_allowlist(user_ip ipaddress, cidr string) {
user_ip.in_cidr(cidr)
}
definition user {}
definition group {
relation member: user
}
definition organization {
relation admin: user
}
definition folder {
relation org: organization
relation parent: folder
relation viewer: user | group#member
permission view = viewer + parent->view + org->admin
}
definition document {
relation folder: folder
relation owner: user
relation editor: user with ip_allowlist
relation viewer: user | user:*
relation guest: user with expiration
relation banned: user
permission edit = owner + editor
permission view = (viewer + guest + edit + folder->view) - banned
}
The relationships become derived roles
Each way a person can be related to a document becomes a derived role. The editor's IP caveat becomes part of the editor condition, the wildcard becomes a public flag, and the expiring guest grant becomes a timestamp.
# derived_roles.yaml
apiVersion: api.cerbos.dev/v1
derivedRoles:
name: document_relationships
definitions:
- name: owner
parentRoles: ["user"]
condition:
match:
expr: R.attr.owner == P.id
- name: editor
parentRoles: ["user"]
condition:
match:
all:
of:
- expr: P.id in R.attr.editors
- expr: >-
!has(R.attr.editorCidr) ||
P.attr.ipAddress.inIPAddrRange(R.attr.editorCidr)
- name: direct_viewer
parentRoles: ["user"]
condition:
match:
any:
of:
- expr: P.id in R.attr.viewers
- expr: R.attr.public == true
- name: guest_viewer
parentRoles: ["user"]
condition:
match:
all:
of:
- expr: P.id in R.attr.guestShares
- expr: now() < timestamp(R.attr.guestShares[P.id])
- name: folder_viewer
parentRoles: ["user"]
condition:
match:
expr: R.attr.folderId in P.attr.viewableFolders
The permissions become rules
The two permissions become allow rules, and the exclusion becomes a deny rule that wins over every allow.
# document.yaml
apiVersion: api.cerbos.dev/v1
resourcePolicy:
resource: document
version: default
importDerivedRoles:
- document_relationships
rules:
- actions: ["edit"]
effect: EFFECT_ALLOW
derivedRoles: ["owner", "editor"]
- actions: ["view"]
effect: EFFECT_ALLOW
derivedRoles: ["owner", "editor", "direct_viewer", "guest_viewer", "folder_viewer"]
- actions: ["view"]
effect: EFFECT_DENY
roles: ["*"]
condition:
match:
expr: P.id in R.attr.banned
The folder chain, parent->view and org->admin, stays out of the policy. Your folder table already knows each folder's parent and organization, so Cerbos Synapse or the application queries it before the check and sends the folders the person can view, including those reached through their groups and through organization admin rights. For deep or very large trees, keep the tree where it is, in your database or a graph database, and let Cerbos Synapse query it and return only the answer.
Port the tests with the policy
Turn your SpiceDB assertions into a Cerbos test suite. This one pins the clock so the expiring grant can be tested, and covers each relationship, the IP caveat, the expired guest, the banned user and the public document.
# tests/document_test.yaml
name: DocumentTestSuite
options:
now: "2026-11-01T09:00:00Z"
principals:
anne:
id: anne
roles: ["user"]
attr: {ipAddress: "10.1.2.3", viewableFolders: []}
anne_remote:
id: anne
roles: ["user"]
attr: {ipAddress: "203.0.113.7", viewableFolders: []}
bob:
id: bob
roles: ["user"]
attr: {ipAddress: "10.1.2.4", viewableFolders: ["finance"]}
carol:
id: carol
roles: ["user"]
attr: {ipAddress: "10.1.2.5", viewableFolders: []}
dan:
id: dan
roles: ["user"]
attr: {ipAddress: "10.1.2.6", viewableFolders: ["finance"]}
erin:
id: erin
roles: ["user"]
attr: {ipAddress: "10.1.2.7", viewableFolders: []}
owen:
id: owen
roles: ["user"]
attr: {ipAddress: "198.51.100.9", viewableFolders: []}
resources:
q3plan:
kind: document
id: q3plan
attr:
owner: owen
editors: ["anne"]
editorCidr: "10.0.0.0/8"
viewers: []
public: false
guestShares: {carol: "2026-12-31T23:59:59Z", erin: "2026-10-01T00:00:00Z"}
folderId: finance
banned: ["dan"]
handbook:
kind: document
id: handbook
attr:
owner: owen
editors: []
viewers: []
public: true
guestShares: {}
folderId: hr
banned: []
tests:
- name: q3plan
input:
principals: ["owen", "anne", "anne_remote", "bob", "carol", "dan", "erin"]
resources: ["q3plan"]
actions: ["view", "edit"]
expected:
- {principal: owen, resource: q3plan, actions: {view: EFFECT_ALLOW, edit: EFFECT_ALLOW}}
- {principal: anne, resource: q3plan, actions: {view: EFFECT_ALLOW, edit: EFFECT_ALLOW}}
- {principal: anne_remote, resource: q3plan, actions: {view: EFFECT_DENY, edit: EFFECT_DENY}}
- {principal: bob, resource: q3plan, actions: {view: EFFECT_ALLOW, edit: EFFECT_DENY}}
- {principal: carol, resource: q3plan, actions: {view: EFFECT_ALLOW, edit: EFFECT_DENY}}
- {principal: dan, resource: q3plan, actions: {view: EFFECT_DENY, edit: EFFECT_DENY}}
- {principal: erin, resource: q3plan, actions: {view: EFFECT_DENY, edit: EFFECT_DENY}}
- name: public handbook
input:
principals: ["erin", "dan"]
resources: ["handbook"]
actions: ["view", "edit"]
expected:
- {principal: erin, resource: handbook, actions: {view: EFFECT_ALLOW, edit: EFFECT_DENY}}
- {principal: dan, resource: handbook, actions: {view: EFFECT_ALLOW, edit: EFFECT_DENY}}
Run cerbos compile on the folder and all 18 tests pass with Cerbos 0.57.0. Anne edits from the office network and is denied from home, Carol's guest grant is live and Erin's has expired, Dan sees the folder but is banned from the document.
Note one behavior that changes. When a SpiceDB check is missing caveat context, it returns a conditional result and leaves the decision to you. A Cerbos condition that cannot be satisfied simply does not grant access, so a missing IP address means no edit. Decide up front which attributes every request must carry, record them in a policy schema, and set schema enforcement to reject in the PDP configuration, so a request without them is denied.
Where your SpiceDB data goes after the migration
Export the relationships once, with zed backup create or the ExportBulkRelationships API, and group them by resource type and relation. For each group, find where the fact is already held.
-
Owners, editors, document viewers and folder membership are usually rows or columns your application already stores, because the tuples were written from them. The application loads them with the record and sends them as resource attributes.
-
Group membership and organization admins belong to your identity provider. They arrive in the person's token, or Cerbos Synapse reads them from Okta, Entra ID or another directory at decision time. Read through Cerbos Synapse, a leaver loses access on the next decision, within the cache time you set. Read from a token, it takes until the token is reissued.
-
Folder and organization trees stay in your database or a graph database. Cerbos Synapse queries them before the check and returns the resolved answer.
-
Caveat context stored on relationships, such as an IP range, becomes a column on the record it constrains. Expiring relationships become a timestamp on the share.
-
Tuples with no other home exist only in SpiceDB, often sharing data that SpiceDB became the source of truth for. Move them into a table in your own database before cutover. The export gives you the data to load.
Once each group has a home, your application keeps only its existing write path. The extra tuple writes, the outbox or change data capture job and the reconciliation checks can all be deleted.
Replacing SpiceDB's calls with Cerbos
CheckPermission becomes CheckResources
A SpiceDB check names a resource, a permission and a subject, and often a ZedToken for freshness. A Cerbos check sends the person and the resource with their attributes, and can ask about several actions at once.
import { GRPC } from "@cerbos/grpc";
const cerbos = new GRPC("localhost:3593", { tls: false });
const decision = await cerbos.checkResource({
principal: {
id: user.id,
roles: ["user"],
attr: { ipAddress: req.ip, viewableFolders },
},
resource: {
kind: "document",
id: doc.id,
attr: {
owner: doc.ownerId,
editors: doc.editorIds,
editorCidr: doc.editorCidr,
viewers: doc.viewerIds,
public: doc.isPublic,
guestShares: doc.guestShares,
folderId: doc.folderId,
banned: doc.bannedIds,
},
},
actions: ["view", "edit"],
});
if (!decision.isAllowed("edit")) {
throw new ForbiddenError();
}
CheckBulkPermissions becomes the same call with several resources, checkResources, and the response answers each resource and action.
LookupResources becomes PlanResources
LookupResources walks the stored relationships and returns IDs that your application then loads. In Cerbos, a query plan turns the policy into a filter, and an adapter adds it to the query you already run, so the database returns the documents the person can view, sorted and paginated as usual. Documented adapters cover Prisma, Drizzle, Mongoose, Convex, SQLAlchemy and LangChain with ChromaDB for retrieval.
LookupSubjects and the sharing dialog
"Who can see this document?" becomes a query on the tables that now hold the shares and memberships, joined with the folder tree, which is usually what a sharing dialog needs anyway.
ZedTokens and consistency
ZedTokens existed so a check would not use relationship data older than the last change. With no tuple store, nothing lags the source except the cache times you choose. Facts the application sends are as current as the row it loaded, and facts from Cerbos Synapse are as current as the cache time you set for that source. Set no caching, or a short cache time, for revocation-sensitive data such as group membership and bans. Remove ZedToken storage and passing from your code as part of the cutover.
Running Cerbos beside SpiceDB in shadow mode
Before any decision depends on Cerbos, send the same requests to both. SpiceDB keeps enforcing, Cerbos runs alongside, and a small wrapper logs every disagreement with the inputs on both sides. The Cerbos call runs off the request path, so a failure there never changes what SpiceDB returns.
const spice = await spicedbCheck(doc.id, "view", user.id);
cerbos
.checkResource({ principal, resource, actions: ["view"] })
.then((cerbosDecision) => {
if (spice.allowed !== cerbosDecision.isAllowed("view")) {
logger.warn("authz_mismatch", { docId: doc.id, userId: user.id, spice, cerbos: cerbosDecision });
}
})
.catch((err) => logger.error("cerbos_shadow_error", { docId: doc.id, err }));
return spice.allowed;
Most mismatches in the first week are data, not policy. An attribute the request did not carry, a group the token did not include, a folder chain resolved differently. Treat a conditional result from SpiceDB as its own category until you know which context it was missing. Cerbos Hub's decision logs give you the Cerbos side of each mismatch with the policy version, so the review needs no extra logging.
Cutting over and decommissioning SpiceDB
Move one resource type at a time. When a type has run in shadow mode with zero unexplained mismatches for long enough to cover your normal traffic, including month end or whatever cycle your product has, switch enforcement to Cerbos for that type and keep SpiceDB answering in the background for a short rollback window.
After the last type moves, stop the tuple writes, remove the outbox or change data capture job, take a final zed backup create for your records, and retire the datastore. That removes a stateful cluster, a sync pipeline and their alerts, and leaves one decision log for every resource type.

Common challenges when migrating from SpiceDB, and how to solve them
Deep or wide folder trees. Do not pass the whole tree into the request. Let Cerbos Synapse query it and return the folders a person can view, and cache that answer for as long as your revocation needs allow.
Relationships that only ever lived in SpiceDB. Find them in the export by checking which tuples have no matching row in your database, and give them a table before cutover.
Caveats with functions Cerbos names differently. Both use CEL, but helper functions differ. SpiceDB's in_cidr is inIPAddrRange in Cerbos, and the conditions reference lists the rest. The tests catch any you miss.
Large group fan out. A person in hundreds of groups is better served by Cerbos Synapse reading the directory than by a token carrying every group.
Lists that relied on LookupResources. Move them to query plans resource type by resource type, together with that type's checks, so a list and a check never disagree.
Planning your SpiceDB migration
Start with the resource type that has the fewest relations and enough traffic to show mismatches within a week, often documents or projects. Map its tuples to their real homes, translate its definition, port its assertions to tests, run it in shadow mode, then cut it over. Each type after that is faster, because the identity provider and Cerbos Synapse lookups are already in place.
As Rob Crowe, Principal Engineer at Utility Warehouse, put it, "Cerbos dropped right into our stack. We didn't need to rewrite anything or rethink how we deploy."
Try Cerbos with a definition from your own schema. Your engineers delete a datastore and a sync pipeline instead of maintaining them, your identity team can point to the directory or table that supplies every relationship, and your security team gets a decision log for each resource type from its first day in shadow mode.
To plan the move from SpiceDB, book a call with our team, bring your schema and the tuple counts per relation, and we will map each relation to the system that should supply it after the move.
Go deeper:
FAQ
Tagged in






