Getting Started with Auth0 Relationship Sync

Auth0 Relationship Sync is currently in Beta, available to a limited set of customers. Don’t use it against a production FGA store.

Overview

Auth0 Relationship Sync lets you use the Auth0 Events API to update FGA. Changes to supported Auth0 entities, made through the Auth0 Dashboard, the Management API, or an upstream connection such as SCIM, produce events. Relationship Sync consumes them and applies your mapping rules to write or delete FGA tuples. What to expect:

Every event FGA consumes is applied to your store.
Auth0 doesn’t guarantee that every change produces an event, or that events arrive in order when changes race. See Event delivery and consistency.
You are responsible for reconciling FGA against Auth0 periodically.

This guide walks you through setting up Auth0 Relationship Sync end to end. Here’s what you’ll do:

Write an FGA authorization model into your store
Create a Sync pipeline by connecting to Auth0 and verifying your credentials
Create a mapping file that tells the pipeline how to transform Auth0 events into FGA tuples
Verify that tuples are syncing by making a change in Auth0 and checking FGA

Before you start

Before setting up Auth0 Relationship Sync, you need:

An Auth0 tenant.
An FGA store.

Understand the model

Your FGA model needs a type and relation for the mapping rules to write to. This minimal slice is enough for the example in this guide: adding and removing a user from an organization. You can grow into a fuller model later as you map more events; see Use-Cases for complete, end-to-end mappings covering tenant roles and SCIM groups.

Write the model into your FGA store

Before you can select this model in the setup wizard below, it needs to exist in your FGA store. In the FGA Dashboard, open Model Explorer, paste the model above into the editor panel, and click SAVE. See Managing Models if you’re setting up your store for the first time.

Create the pipeline

In the FGA Dashboard, go to Auth0 Relationship Sync in the sidebar to start the setup wizard and create the Sync pipeline.

01. Name Your Pipeline

Give the Sync pipeline a friendly name to identify it later.

02. Create a Machine-to-Machine (M2M) Application in Auth0

In the Auth0 tenant you want to read events from, create a Machine-to-Machine application, authorize it to call the Auth0 Management API with the read:events scope, then enter your Auth0 Tenant Domain and the application’s Client ID.

03. Establish Private Key JWT Connection to Auth0 Application

FGA generates an RSA key pair and shows you the public key as a downloadable PEM certificate. Upload it to Auth0 as a Private Key JWT credential on the same Machine-to-Machine application, then click Verify Connection.

FGA imposes no expiration of its own on this key; its validity is entirely governed by the credential’s expiration setting on the Auth0 side (Never, From certificate, or a Custom date). Auth0 does not notify you ahead of an upcoming expiry. If you set a Custom date, you’re responsible for rotating the key on the Auth0 side before it lapses (see Rotating credentials), otherwise the Sync pipeline will stop authenticating once it passes, with no advance warning from either side.

If verification fails, you’ll see a Key validation failed message; download the key again and re-upload it to your Auth0 application. See Troubleshooting if it keeps failing. Once verified, the wizard finishes and creates the Sync pipeline.

Understand the mapping

A mapping file is a YAML document that tells the Sync pipeline how to transform Auth0 events into FGA tuples, one rule per event. Here’s the smallest version that does something useful: adding and removing a user from an organization.

version: "1"

rules:
  - name: "Add user to organization"
    when: input.type == "organization.member.added"
    variables:
      organization_id: input.data.object.organization.id
      user_id: input.data.object.user.user_id
    tuples:
      - user: "user:{{ variables.user_id }}"
        relation: "member"
        object: "organization:{{ variables.organization_id }}"

  - name: "Remove user from organization"
    when: input.type == "organization.member.deleted"
    variables:
      organization_id: input.data.object.organization.id
      user_id: input.data.object.user.user_id
    tuples:
      - action: delete
        user: "user:{{ variables.user_id }}"
        relation: "member"
        object: "organization:{{ variables.organization_id }}"

These rules fire whenever Auth0 emits organization.member.added or organization.member.deleted to write or delete the corresponding tuples.

Add a model and mapping

The Sync pipeline exists but sits idle until it has a model and mapping. From its Add Mappings to Pipeline page, select the model you wrote into your store above, paste the mapping YAML above into the Mappings field, and click Add Mappings. FGA validates that your mapping is compatible with the selected model, for example that every relation it writes to actually exists on that model, and returns diagnostic details if it isn’t.

Verify it’s working

Confirm the Sync pipeline end to end: start it, trigger a real change in Auth0, then check that the resulting tuple landed in FGA.

1. Start the pipeline

Back on the pipeline’s overview, click Start, now enabled since a mapping exists. You’ll be asked to confirm, since this begins processing events immediately. By default, the Sync pipeline starts from the current time: any Auth0 data that already existed is not synced retroactively (see Backfilling and reconciling if you need to backfill existing data). You can instead start from a specific point in the past, up to 7 days back.

2. Trigger a change in Auth0

Add yourself, or a test user, as a member of an organization in your Auth0 tenant; this fires the same organization.member.added event the minimal mapping above maps. In the Auth0 Dashboard, go to Organizations, select the organization, select the Members view, select Add members → Add Users, enter the user, then select Add user(s) to organization. See Auth0’s Assign Members doc for the full flow, including the Management API equivalent.

3. Confirm the tuple landed in FGA

Pick one method below and check FGA a few seconds after the change in step 2: you should see a tuple with your user as the user and member as the relation. Dashboard:

Open the FGA Dashboard’s Tuple Management page
Type the organization’s ID (e.g. org456) into the Type to filter tuples… box on the left, under Tuples. It’s a plain substring match against the list already loaded on the page, so a partial ID works too. The page loads only the first 1000 tuples, so in a larger store the tuple may not show up even though it exists; use the CLI below to check reliably.

CLI:

fga tuple read --store-id=<your-store-id> --user user:user123 --object organization:org456

The Read API requires an --object whenever you filter by --user.
Pass --object organization: (type only, no ID) if you don’t have a specific organization ID yet.
If the user ID contains a pipe character, common for Auth0 IDs like auth0|abc123, quote it so your shell doesn’t treat the | as a pipe operator: --user 'user:auth0|abc123'.

To see the delete side too, remove the user from the organization in Auth0 (same Members view as step 2). This fires organization.member.deleted, and the tuple should disappear within a few seconds: gone from the dashboard list, or an empty result from the CLI. If tuples don’t appear or disappear as expected, see Troubleshooting.

Next steps

You’ve deployed the minimal model and mapping this guide provides. To map more of your own Auth0 data:

Supported Auth0 events — the events this documentation covers, and known limitations to plan around. Other Auth0 event types can be mapped the same way, but aren’t covered by the use cases.
Use-Cases — complete, end-to-end mappings covering tenant roles, SCIM groups, and other authorization shapes on top of the organization membership rules above.
Mapping Language — the full mapping-file syntax: tuple filters, iterators, the expression language, and embedded tests.
Working with Mapping Files — write, validate, and test mappings locally before pasting them into the dashboard.

Introduction to Auth0 FGA

Permissions Index

FGA Dashboard

Define your authorization model

Write Your Authorization Data

Add Authorization To Your API

Auth0 Relationship Sync

Advanced Modeling

Deprecation Notices & Migrations

Getting Started with Auth0 Relationship Sync

Overview

Before you start

Understand the model

Write the model into your FGA store

Create the pipeline

01. Name Your Pipeline

02. Create a Machine-to-Machine (M2M) Application in Auth0

03. Establish Private Key JWT Connection to Auth0 Application

Understand the mapping

Add a model and mapping

Verify it’s working

1. Start the pipeline

2. Trigger a change in Auth0

3. Confirm the tuple landed in FGA

Next steps

​Overview

​Before you start

​Understand the model

​Write the model into your FGA store

​Create the pipeline

​01. Name Your Pipeline

​02. Create a Machine-to-Machine (M2M) Application in Auth0

​03. Establish Private Key JWT Connection to Auth0 Application

​Understand the mapping

​Add a model and mapping

​Verify it’s working

​1. Start the pipeline

​2. Trigger a change in Auth0

​3. Confirm the tuple landed in FGA

​Next steps

Overview

Before you start

Understand the model

Write the model into your FGA store

Create the pipeline

01. Name Your Pipeline

02. Create a Machine-to-Machine (M2M) Application in Auth0

03. Establish Private Key JWT Connection to Auth0 Application

Understand the mapping

Add a model and mapping

Verify it’s working

1. Start the pipeline

2. Trigger a change in Auth0

3. Confirm the tuple landed in FGA

Next steps