Pause and resume
Pause sits at the top of the pipeline’s detail page, next to its status badge, and asks you to confirm before taking effect. Pausing stops the worker from consuming new events; events themselves aren’t lost immediately, since the Auth0 Events API retains them for a limited time, so you can catch up once you resume. The retention period isn’t documented by Auth0 yet, so don’t assume a specific duration; an expired position is rejected with a410 (see the Events API error responses).
Once paused, the Sync pipeline shows a Paused badge, and the header now offers Resume alongside Delete (Delete only appears once the pipeline is paused; see Delete a Sync pipeline below). Resuming also asks you to confirm.
By default, Resume continues syncing from the last cursor it had processed, with no explicit time limit on your side; events held during the pause are delivered and processed in order, up to the Auth0 Events API’s retention limit (see Reconciling below). If that retention is exceeded, the cursor is lost and events in the gap are silently not replayed; see the PAUSED_CURSOR_LOST row in the status reference below.
You can instead resume from an explicit point in time rather than the last cursor. This is capped at 7 days back. See Troubleshooting if you hit this.
Change the model or mapping
A mapping is only ever valid against a specific model, since the relations it writes to have to exist on that model. Both live on the same Mappings tab: a Model dropdown (with a view icon to inspect the selected model’s schema) above the Mappings field. There’s no separate model-picker flow; changing the model is just selecting a different one from that same dropdown. To change either, update the dropdown selection and/or the mapping YAML as needed, then click Update Mappings. Because your mapping may reference relations that don’t exist on the newly selected model, saving re-runs the same mapping/model compatibility check from setup. If it fails, you’ll see diagnostics so you can fix the mapping (or pick a different model) before saving; a failed validation has zero effect. The Sync pipeline keeps running exactly as it was, on its previous model and mapping, as if the save had never happened. See Validating a mapping file for what gets checked. The worker picks up the change automatically, with no restart or downtime required.Mappings are not versioned today: updating a mapping overwrites it, with no history of prior versions and no built-in way to roll back. Keep your own copy of a mapping file before changing it if you want to be able to revert.
Delete a Sync pipeline
A Sync pipeline must be paused before it can be deleted; pause it first if it’s still active. Delete only appears at the top of the pipeline’s detail page, alongside Resume, once the pipeline is paused; it’s hidden entirely while a pipeline is Active. You’re asked to type the pipeline’s name to confirm, and this cannot be undone. Deleting stops the worker and removes the Sync pipeline’s mapping and public key. The FGA tuples already written to your store are not affected; you manage those directly in FGA, independent of the Sync pipeline that created them. After deleting, you’re returned to the empty Auth0 Relationship Sync page, ready to set up a new one, for example to connect a different tenant.Rotating credentials
FGA imposes no expiration of its own on the signing key. The sole source of truth for how long it stays valid is your Auth0 client’s own credential configuration: Never, From certificate, or a Custom date, set on the Machine-to-Machine application’s Private Key JWT credential in Auth0. Auth0 does not send a notification ahead of any of these, so either set the expiration to Never and rotate on your own schedule, or set an actual date and configure your own reminder on the Auth0 side before it lapses; nothing on the FGA side will warn you. Rotation is available on demand at any time; nothing on the FGA side forces it on a schedule. A Sync pipeline keeps at most two keys at once: an Active key, and, while you’re mid-rotation, a Candidate. Because a Candidate occupies the second slot, a lost or rejected Candidate has to be deleted before you can add another; see If you lose a certificate.01. Generate a new key
On the Credentials tab, click + Public Key. FGA generates a new RSA key pair and lists it as a Candidate, downloadable as an RS256 PEM certificate. You can download the certificate only once, so download it and add it to Auth0 (step 02) before you move on.02. Add the new key to Auth0
Upload the new PEM certificate to your Machine-to-Machine application as an additional Private Key JWT credential; see Auth0’s Rotate credentials guide for the current steps. Auth0 supports multiple registered keys at once, so your current Active key keeps working while you do this.03. Promote the new key
Back on the Credentials tab, use the Candidate key’s … menu to promote it. This flips it to Active, and the worker immediately switches to signing with the new key. The key it replaces is relabeled Deprecated.04. Remove the old key from Auth0
Once the new key is confirmed working, remove the old key’s credentials from your Auth0 application, then delete the Deprecated key from the Credentials tab’s … menu. You’re asked to type the application’s name to confirm, and this cannot be undone; the warning is scoped to the one key, not the whole Sync pipeline.If you lose a certificate
The certificate for a key can be downloaded only once. FGA doesn’t keep a copy you can retrieve later.- You lost a Candidate’s certificate, or it didn’t work in Auth0. Delete the Candidate from its … menu (Delete Key), remove it from your Auth0 application if you had already uploaded it, and click + Public Key to generate a new one. Start again from step 02. Your Active key keeps working throughout.
- You lost the Active key’s certificate after uploading it to Auth0. Nothing to do while that credential stays registered and unexpired in Auth0. The file holds only the public key and is needed only to register it, so losing it isn’t a reason to rotate on its own. Rotate (see Rotating credentials) if the credential is removed from Auth0, its expiration passes, or the key may be compromised, and otherwise on your usual schedule.
- The pipeline hasn’t been verified yet. See Key validation failed at setup.
Backfilling and reconciling
Auth0 Relationship Sync processes events from the moment the Sync pipeline is activated; it does not import historical Auth0 data automatically. There are three situations where the FGA store can fall out of sync and require manual reconciliation. Backfilling and reconciling both start with a complete Auth0 Management API snapshot, but they are different operations. An initial backfill writes missing tuples; repairing drift must also read FGA and delete stale tuples that Auth0 no longer authorizes.When you need to reconcile
Initial setup (backfill): any Auth0 data that existed before the Sync pipeline was activated (users, organization memberships, role assignments, groups) is not in FGA. You need to backfill it before going live. Extended downtime: FGA has no queue of its own; whether you pause the Sync pipeline yourself or it’s paused/disconnected automatically, the only thing standing between you and lost events is the Auth0 Events API’s own retention window, bounding how far back a Sync pipeline can resume from. If this window is exceeded, the events inside it are gone and the Sync pipeline cannot replay them on resume. Reconcile against the Management API snapshot, including deletions of grants left by missed removal events, within the scope your rules’tuple_filters cover (see How to reconcile). This surfaces as the PAUSED_CURSOR_LOST status; see Sync pipeline status reference.
Mapping or model changes that affect synced tuples: see Change the model or mapping above for how to make the change itself; this covers when the change also requires reconciling tuples that were already synced. Not every change requires reconciliation. Only changes that alter how already-processed events produce tuples need it:
- Requires reconciliation: renaming a relation, changing the
user:orobject:template in an existing rule, removing a rule that was previously writing tuples, changing role normalization logic; also adding a new relation that should apply to existing Auth0 data (the Sync pipeline won’t retroactively process old events to populate it). - Does not require reconciliation: adding a new rule for an event type that wasn’t previously mapped (no old tuples to fix), adding a new relation type that your application populates directly.
fga mapping sync --dry-run previews the writes and deletes for the scope your rules cover, and an empty plan means no drift in that scope. Start from How to reconcile below using the Auth0 Management API as the source of truth. Since drift from a missed event can happen at any time and without warning, plan to run this check periodically rather than only when you happen to notice something wrong.
How to reconcile
Take a complete, paginated snapshot of the Auth0 entities your mapping owns. Choose the operation that matches your goal: Initial backfill only:fga mapping evaluate + fga tuple write. Export the Auth0 state as a JSONL stream of synthetic events (one per user, membership, role assignment, etc.), feed it through your existing mapping file, and write the result to an empty or otherwise known-clean FGA scope:
--aggregate processes the whole batch instead of emitting record-by-record results. This is not drift repair: --writes-only removes deletes from the output, and fga tuple write does not compare the output with existing FGA tuples. Re-running it cannot detect or revoke a grant left behind by a deleted role (which emits no event), a missed membership removal, or a mapping change. Some mapping rules use tuple_filters, which an offline run cannot resolve without reading FGA. See Working with Mapping Files for the CLI reference.
Ongoing reconciliation: fga mapping sync. Feed the snapshot through fga mapping sync, one synthetic event per Auth0 entity. Unlike fga mapping evaluate, sync reads your FGA store. For a rule with tuple_filters, it reads the tuples that match the filters, compares them with the tuples the rule produces, writes the missing ones, and deletes the extra ones. It sends deletes before writes, so a changed condition does not collide with its replacement. It needs OpenFGA CLI v0.8.2 or later.
plan.jsonl is for review only. The apply evaluates snapshot.jsonl again and reads the store again. Pause the pipeline before you capture the snapshot, and resume it within its event-retention window after the apply. Events that arrive during the pause are replayed when you resume. If you export before pausing, events the pipeline processes in between are missing from the snapshot, and the apply reverts them.
The direct connection memberships mapping is an example. Feed each user from the Management API as a user.updated event, and the rule makes that user’s direct_member tuples match their current identities. It adds the missing tuples and removes the stale ones. A second run produces an empty plan.
sync repairs only what the mapping and your input cover:
- Scope. A rule repairs the tuples its
tuple_filtersmatch, for the records you feed it. A tuple outside every filter’s scope is never touched, and an entity that is not in the snapshot is never visited. To remove the tuples of a deleted user, feed auser.deletedrecord. - Rule shape. Reconciliation needs rules that pair
tuple_filterswith the desired tuples. A filter withaction: deleteremoves every tuple it matches, which is how auser.deletedrule clears a user. A rule that only writes or deletes fully specified tuples applies exactly those. Rules that react to a removal event, such asorganization.member.role.deleted, do nothing for an entity whose removal event you did not send. - Safety. A reconcile filter (one without
action: delete) in a rule that produces no desired tuples is rejected instead of deleting everything it matches. A rule whose desired tuples are wrong or incomplete still deletes valid grants in its scope. Do not delete tuples written by your application or another Sync pipeline, and review the dry-run output before you apply. An incomplete export can turn valid grants into deletes. - Atomicity.
syncis not transactional: a failure partway leaves a partial result. Re-running is safe, because it ignores duplicate writes and missing deletes, and it exits non-zero if a record fails. Use--continue-on-errorto skip a failing record and keep going. See Applying a mapping to a store for the rest.
plan.jsonl is empty, then resume the pipeline.
Cleaning up tuples that no rule covers
sync cannot remove tuples outside every rule’s tuple_filters: the grants of a deleted role, or the tuples left by a renamed relation, a changed template, or a removed rule. Do not delete roles in your Auth0 tenant while you use Relationship Sync. Auth0 emits no event for a role deletion, so no rule can react, and sync does not visit the deleted role either. An empty dry-run plan does not mean those grants are gone.
If you have deleted a role, find its objects, review what is stored, and delete them. You need the deleted role’s ID, which the Management API can no longer return, so take it from your own records. A read by exact object does not need a user, but a read by bare type, such as organization_role:, fails without one. List your organizations from the Management API and read each organization’s copy of the role by its object ID. Use --output-format=simple-json, which fga tuple delete --file accepts, and --max-pages 0: by default the read stops after 20 pages (1000 tuples) without warning.
role:{role_id} the same way. Review stale.json and delete from the file any tuple you want to keep. Then delete the rest from the store:
[], or only the tuples you kept.
Handling stale tuples after a mapping change
If you are reconciling because your mapping changed, FGA may contain tuples written by the old mapping that are no longer correct. You have two options: Clear first, then write new: delete stale tuples before writing the new ones. Avoids a mixed state with contradictory permissions, but causes a brief window where affected users have no permissions. Write new, clean up after: write the new tuples first so users always have valid access, then identify and delete stale tuples. Safer for access continuity but risks a brief period where both old and new tuples coexist. Which to prefer depends on whether the old and new tuples are contradictory (e.g., granting access where none should exist) or just redundant. Neither option has a universal “right” answer; match your application’s tolerance for access gaps vs. overly permissive states. A live Sync rule withtuple_filters can read, diff, and write the desired state for an affected object when a matching event is processed. It cannot repair an object whose removal event was missed. To repair old or missing grants, use fga mapping sync for the scope your rules’ tuple_filters cover, and clean up tuples that no rule covers for anything outside it. To find the tuples an old mapping left behind, read the affected objects as described there, or read by --user together with an object type (for example --user 'user:auth0|abc123' --object organization:), with the same --output-format=simple-json --max-pages 0 flags.