We’ve helped many customers migrate from other authorization solutions, so we know where the common pain points are. We also know how important it is to pick your next vendor.

This guide explains how you can migrate quickly and safely — and we’ll also explain why we think you’ll be better off by the end of it.

Summary

• We’ve invested heavily in making it easy to migrate:
  • Bring your own database: You don’t need to re-sync everything into Oso. If some authorization-relevant data already lives in your own database, Oso can use that as part of the overall evaluation. Centralize only what is necessary.
  • Move fast with our specialized migration and development tooling: Oso Migrate is tailor-made for migrating authorization logic from a legacy system, getting to parity with it as quickly as possible and iterating on new logic after that in a fast feedback loop.
• You’ll be better off by the end of the migration:
  • Our core engine has been carefully crafted by experts: We’ve been doing this for 5+ years, and have benefited from experts like Abhishek Parmar (co-creator of Google Zanzibar), our longtime technical advisor.
  • Our engine is built on Facts — an extension of the simple tuples that Zanzibar is based on. This fundamental decision unlocks value for engineers at every level of the system — it’s easier to write logic and perform the queries necessary to meet enterprise-grade requirements (e.g. custom roles, sharing, and more) with Oso.
• We’re a safe, long-term partner:
  • We’re backed by the world’s best investors: Our lead investors are Sequoia, Felicis and we have a standout group of infrastructure founders and operators: Olivier Pomel (Founder, Datadog), Guy Podjarny (Founder, Snyk), Calvin French-Owen (Founder, Segment) and many others.
  • We’re already trusted by leading companies: Vanta, Webflow, Brex, Productboard, Duolingo, and many others already trust us to be a critical part of their infrastructure.

How to migrate to Oso

Step 1: Identify a permission check to migrate

If this is the first permission check that you are migrating, pick one that is low impact, well-understood and straightforward to extract.

The goal is to build confidence as quickly as possible. Picking a low-risk permission means you can get going faster without worrying as much about the implications in production.

Once you’ve gotten a permission check working correctly with the new system, you’ll use the patterns you’ve built and confidence to migrate the rest.

Step 2: Model the same logic in our DSL, Polar

Why engineers find Polar easier to read and evolve

WorkOS FGA is heavily inspired by Google Zanzibar which relies on representing everything as relationships.

💡 We’re fans of Zanzibar — in fact, Abhishek Parmar (co-creator of Google Zanzibar) has been a technical advisor to Oso for years. We’ve used this knowledge to build a best-in-class product serving companies like ProductBoard, Webflow, Vanta and Brex.

Oso is a logic engine that relies on Facts as its core data model. Facts are more flexible and expressive than tuples. You can learn more about facts here.

Facts give Oso more flexibility and expressiveness for modelling & querying, and they also enable us to deliver market-leading performance (P90 <10ms).

But why does flexibility and expressiveness matter in practice?

Below is a simple example of Custom Roles — a very common requirement for startups as they go upmarket. We’ve taken the below example from WorkOS’s documentation and modeled it out in Polar so that you can see a side-by-side comparison.

In Polar, on the right-hand side, the logic reads like a business requirement:

A user has a permission on an org if

• they have a role on that org, and
• that role grants the permission

By contrast, the same logic taken from the WorkOS FGA page on the left-hand side requires more mental effort. This rears its head in two ways:

1. It doesn’t really mean anything to be a member on a role. This indirection exists solely to get around the limitation that the relation part in a tuple must be a static string. This limitation does not exist in Oso.
2. You have to add something like can_write_reports if member on can_write_reports [role]  for any new permission you introduce. On initial read, it’s unclear what this logic is doing until you try to reason about it for longer.

How to port over your logic to Oso

Given Oso provides more flexibility than WorkOS FGA, porting over the logic should be easy and shouldn’t require altering too many semantics (though you may wish to clean up the logic along the way, like we did above for Custom Roles).

The below is another example of how one might do that with a policy that involves simple ReBAC (e.g. viewing / editing documents within an Organization).

Reference table

Here’s a detailed mapping of WorkOS FGA to Oso documentation — use this if you’re trying to map between the concepts in both systems

Step 3: Perform the same queries against Oso

WorkOS has two different “ways” of querying for results — the Check API and the Query Language. These can both be mapped into a single, standard approach in Oso. You can read more about our APIs here.

Simple check

Select resources (List filtering)

In applications, it’s a common requirement to figure out “what are all the documents this user can view”? In WorkOS FGA, this would be achieved via their SQL-like Query Language. In Oso, you’d use the list API.

List actions

Applications often send permissions that a user can perform to the frontend in order to make the UI “permissions-aware”, enabling and disabling buttons and forms as required.

In WorkOS, this would be performed via a BatchCheck endpoint. This requires you to specify each of the actions you want to query for client-side.

It’s simpler with Oso — you just query for the actions a user can perform.

Oso has more flexible querying capabilities

Got a more complicated use case?

Perhaps, for performance reasons, you want to do something like query for all documents that a user can view, but only within a particular Organization.

Oso is the only product on the market today which can support this sort of querying flexibility, which is made possible by the flexibility of our core engine that relies on Facts.

Step 4: Feed the same data to Oso

Once you’ve written the logic and wired up the query, you’ll need to feed relevant data so that it can be used as part of the overall evaluation.

Oso gives you the flexibility to use it as part of the overall evaluation in a variety of ways.

Leave it in your own database

You don’t need to move your data into Oso if you don’t want to. Oso can evaluate authorization decisions against your existing tables by deferring part of the evaluation for you to run against your own database.

If you do have data that lives in your own database (and you’ve been dual writing this data to WorkOS FGA), this is potentially a huge time saver for migrating to Oso, since you won’t have to extract it out and sync it to another engine.

Store it in Oso, similar to WorkOS

If you do need to store it in a centralized engine (e.g. because you need to share the data across multiple services or for performance reasons), then you can use our batch api which has similar semantics to the current batchWriteWarrants api:

If this is required, we recommend dual writing between the two systems and doing an initial sync to make sure WorkOS and Oso are consistent with each other. This way, you’ll be able to phase out WorkOS FGA without any downtime.

Step 5: Drive to parity and build confidence

As you do the migration off WorkOS FGA onto a new system, you’ll want to build confidence that Oso and WorkOS FGA are producing the same results so that users don’t experience any disruption.

In order to build confidence, you’ll want to do parity checking to make sure that the results between both systems are consistent. Where there is any deviation, you’ll want to catch these early and remediate as quickly as possible.

Most of Oso’s customers have been in a situation where they’ve had a legacy homegrown system or another vendor that they needed to migrate away from. In order to make this as painless as possible, we’ve built Oso Migrate, which will help you to:

• Capture authorization decisions made in your legacy system through logging.
• Compare them to decisions that have been made by Oso during the migration.
• Debug exactly why Oso Cloud evaluated the way that it did.
• Iterate quickly on your policy with a fast feedback loop.

Read more about the tooling and our guidance around migrations here.

Parity checking

Policy debugger

Conclusion

For teams moving on from WorkOS FGA, Oso offers a straightforward path forward. The goal isn’t just to replace what you had, it’s to make the migration process clear, reduce the risk of surprises, and give you confidence that your permissions model will keep working as your product evolves. With migration tooling, parity checks, and a proven engine, you can focus on your application while knowing your authorization layer is reliable.

Learn more about our guidance on migrations, our product Oso Migrate, and book time with an engineer to discuss your options.