Skip to main content

What Read Expansions Sends You

Each time a tuple is written or deleted in FGA, the Permissions Index incrementally computes every access that the permission change implies and streams one or more expansion events on the Read Expansions endpoint. You store those events as rows in a permissions table next to your application data. The question “which documents can Anne view?” becomes a SQL join instead of an API call per row. To learn how the index keeps up with every permission change, see FGA Permissions Index.

Prerequisites

Before creating an index, make sure you have an Auth0 FGA enterprise subscription. The Permissions Index is not available for free customers. If you are an enterprise customer, you are entitled to 1 index, 1 relation, and 10 million expansions. Any additional usage will require the FGA Permissions Index add-on SKU. You can always delete an index to reduce your entitlements. Make sure the Permissions Index is enabled for your account. When it is, a Permissions Index tab appears in the sidebar when you open a store in the FGA Dashboard. If you don’t see it, get it enabled before continuing.

Save environment variables

Copy these environment variables into your favorite text editor. You fill in the values as you follow the guide, then paste them into your terminal.

Step 1: Create a Test Store and Authorization Model

This guide uses a demo store and model. Create a new store so the guide doesn’t touch your existing FGA data:
  1. Download the demo .fga.yaml file
  2. Navigate to the FGA Dashboard.
  3. Create a new store called permissions-index-demo.
  4. Navigate to the Model Explorer page.
  5. Drag the downloaded permissions-index-demo.fga.yaml file into the Model Explorer to upload the model and tuples.
  6. Select Import model and Import tuples. This will seed your store with the model and tuples.
Uploading the demo model file in the FGA Dashboard Model Explorer The demo defines a simple hierarchy of folder and document types and distributes sample tuples so that each incrementing folder ID contains exactly the number of documents under it. The demo has three moving parts:
  • Folders hold documents. folder:N is the parent of exactly N documents. For example, folder:4 holds document:4-1, document:4-2, document:4-3, and document:4-4.
  • Folder viewers can view every document inside. document#viewer includes viewer from parent, and document#can_view is defined as viewer.
  • Teams can be folder viewers. The store already gives team:design access to folder:3, team:product access to folder:5, and team:engineering access to folder:10. No team has members yet.
Copy the Store ID and Model ID, and update FGA_STORE_ID and FGA_MODEL_ID.

Step 2: Create a Permissions Index

  1. Open the permissions-index-demo store in the top right “Select Store” dropdown.
  2. Select the Permissions Index tab from the sidebar.
  3. Click the Create Index button in the top right.
  4. Select an authorization model, then click Next.
  5. Select one or more relations to index. Select document#can_view to follow this guide, then click Next. Relations that use unsupported modeling features are disabled. Selecting the document#can_view relation in the FGA Dashboard
  6. Click Create Index.
Copy the new Index ID and update FGA_INDEX_ID. You will use it to read expansions from the stream later.
FGA automatically assigns existing compatible authorization model versions to the index, plus assigns any new compatible authorization models created in the future. See migrating between authorization models for what to do if a model is incompatible.

Step 3: Configure Client Credentials

Create client credentials for your application:
  1. In the FGA Dashboard, open Store Settings.
  2. In the Authorized Clients section, click Create Client.
  3. Name the client index-demo and enable these permissions:
    • Read Permissions Index, to call the Read Expansions endpoint.
    • Write and delete tuples, to write the relationship in Step 5.
Copy the Client ID and Client Secret, and update FGA_CLIENT_ID and FGA_CLIENT_SECRET.
If you are using an existing client, make sure to update it with Read Permissions Index access.

Obtain an access token

All FGA API endpoints require a Bearer token. Get one with the OAuth2 client credentials flow, as described in the Call the API guide. Make sure the variables from Save environment variables are set in your terminal before continuing. Then run:
Copy the access_token from the response and set it:
You will need to use two terminals in the next steps. Set the environment variables and FGA_ACCESS_TOKEN in both.
All FGA access tokens are short-lived. Cache the token for reuse and obtain a new one before expiry to avoid interruptions. FGA SDKs handle token caching and refreshing automatically.

Step 4: Open the Read Expansions Stream

Read Expansions is a long-lived NDJSON stream endpoint emitting one JSON event per line, delivered in real-time. In your first terminal, open the stream and leave it running. --no-buffer prints each event as it arrives.
The first connection replays every existing expansion event, then stays open waiting for new events. Also watch for freshness events. These indicate that the index is caught up and waiting for new changes.
When as_fresh_as is recent, the index has caught up to that point. Any event after that comes from your writes.

Step 5: Grant Access, Receive Expansions

In your second terminal, grant Anne viewer access to folder:4 by writing to FGA:
The Write response is empty when it succeeds. Now look at your first terminal. Four events arrived, one for each document in the folder:
Your write changed permissions at the folder level; the expansions resolved to the document level. Each event turns into a row in a database that your application can query to determine access.
  • operation is EXPANSION_OPERATION_INSERT when access is granted and EXPANSION_OPERATION_DELETE when access is revoked.
  • from is a continuation token. You use it in Step 7 to resume the stream from a specific point.
  • subject_relation is set only when the subject is a userset, such as team:design#member in the demo. Store an empty string when it’s absent.

Step 6: Persist the Stream in Your Database

Read Expansions delivers events. It does not maintain a table for your application to query. Your consumer reads each event and applies it to a permissions table in your own database:
On EXPANSION_OPERATION_INSERT, upsert the row. On EXPANSION_OPERATION_DELETE, delete the matching row. The stream can deliver an event more than once, so this keeps replays harmless. See Designing an Idempotent Consumer for a production-ready version. After Step 5, Anne has four rows: document:4-1, document:4-2, document:4-3, and document:4-4. Filter search results with a join, with no FGA API call necessary:

Step 7: Resume After Disconnect

The server closes each stream connection after 5 minutes, and your consumer will need to restart sometimes. You will not want to replay the whole index each time. As you process events, save the from token of the last event you stored. To resume, pass it back. The stream picks up right after that event:

Next Steps

Before you use the Permissions Index in production, read the best practices:
In production, your consumer reads the stream with an FGA SDK instead of curl: