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:- Download the demo .fga.yaml file
- Navigate to the FGA Dashboard.
- Create a new store called
permissions-index-demo. - Navigate to the Model Explorer page.
- Drag the downloaded
permissions-index-demo.fga.yamlfile into the Model Explorer to upload the model and tuples. - Select
Import modelandImport tuples. This will seed your store with the model and tuples.
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:Nis the parent of exactly N documents. For example,folder:4holdsdocument:4-1,document:4-2,document:4-3, anddocument:4-4. - Folder viewers can view every document inside.
document#viewerincludesviewer from parent, anddocument#can_viewis defined asviewer. - Teams can be folder viewers. The store already gives
team:designaccess tofolder:3,team:productaccess tofolder:5, andteam:engineeringaccess tofolder:10. No team has members yet.
FGA_STORE_ID and FGA_MODEL_ID.
Step 2: Create a Permissions Index
-
Open the
permissions-index-demostore in the top right “Select Store” dropdown. - Select the Permissions Index tab from the sidebar.
- Click the Create Index button in the top right.
- Select an authorization model, then click Next.
-
Select one or more relations to index. Select
document#can_viewto follow this guide, then click Next. Relations that use unsupported modeling features are disabled.
- Click Create Index.
FGA_INDEX_ID. You will use it to read expansions from the stream later.
Step 3: Configure Client Credentials
Create client credentials for your application:- In the FGA Dashboard, open Store Settings.
- In the Authorized Clients section, click Create Client.
- Name the client
index-demoand enable these permissions:- Read Permissions Index, to call the Read Expansions endpoint.
- Write and delete tuples, to write the relationship in Step 5.
FGA_CLIENT_ID and FGA_CLIENT_SECRET.
Obtain an access token
All FGA API endpoints require aBearer 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:
access_token from the response and set it:
FGA_ACCESS_TOKEN in both.
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.
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 tofolder:4 by writing to FGA:
operationisEXPANSION_OPERATION_INSERTwhen access is granted andEXPANSION_OPERATION_DELETEwhen access is revoked.fromis a continuation token. You use it in Step 7 to resume the stream from a specific point.subject_relationis set only when the subject is a userset, such asteam:design#memberin 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: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 thefrom 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:- Continuation token management: where to store
fromtokens and when to save them. - Idempotency and deduplication: handling duplicate and out-of-order events.
- Freshness: how current your table is, and when to fall back to
Check. - Migrating between authorization models: what happens to your index when your model changes.
Read Expansions with an FGA SDK
Read Expansions with an FGA SDK
In production, your consumer reads the stream with an FGA SDK instead of
curl:- Node.JS
- Go
- .NET
- Python
- Java