> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fga.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started with Auth0 Relationship Sync

> Set up Auth0 Relationship Sync end to end, from authentication through your first synced tuple.

> [!NOTE]
>
> 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](https://docs.fga.dev/relationship-sync/overview.md#event-delivery-and-consistency).
* You are responsible for [reconciling](https://docs.fga.dev/relationship-sync/managing.md#reconciling) FGA against Auth0 periodically.

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

1. Write an FGA authorization model into your store
2. Create a Sync pipeline by connecting to Auth0 and verifying your credentials
3. Create a mapping file that tells the pipeline how to transform Auth0 events into FGA tuples
4. 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.

FGA model · DSL

You can grow into a fuller model later as you map more events; see [Use-Cases](https://docs.fga.dev/relationship-sync/use-cases/b2b-organizations.md) 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](https://docs.fga.dev/intro/models.md) 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**.

> [!NOTE]
>
> 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](https://docs.fga.dev/relationship-sync/managing.md#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](https://docs.fga.dev/relationship-sync/troubleshooting.md#key-validation-failed-at-setup) 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.

```yaml theme={null}
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](#write-the-model-into-your-fga-store), 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](https://docs.fga.dev/relationship-sync/managing.md#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](https://auth0.com/docs/manage-users/organizations/configure-organizations/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:**

1. Open the FGA Dashboard's **Tuple Management** page
2. 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:**

```bash theme={null}
fga tuple read --store-id=<your-store-id> --user user:user123 --object organization:org456
```

> [!NOTE]
>
> * 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](https://docs.fga.dev/relationship-sync/troubleshooting.md).

## Next steps

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

* [Supported Auth0 events](https://docs.fga.dev/relationship-sync/overview.md#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](https://docs.fga.dev/relationship-sync/use-cases/b2b-organizations.md) — complete, end-to-end mappings covering tenant roles, SCIM groups, and other authorization shapes on top of the organization membership rules above.
* [Mapping Language](https://docs.fga.dev/relationship-sync/mapping-language.md) — the full mapping-file syntax: tuple filters, iterators, the expression language, and embedded tests.
* [Working with Mapping Files](https://docs.fga.dev/relationship-sync/mapping-files.md#using-the-cli) — write, validate, and test mappings locally before pasting them into the dashboard.