curl

# Set FGA_API_URL to your store region (https://api.us1.fga.dev, or eu1/au1).
# Set FGA_STORE_ID and obtain FGA_BEARER_TOKEN with the client credentials grant.
# See /integration/getting-your-api-keys; never put client secrets in source code.
# Set FGA_MODEL_ID to the authorization model ID.
# Set FGA_INDEX_ID to the permissions index ID.

curl -X GET "$FGA_API_URL/stores/$FGA_STORE_ID/indexes/$FGA_INDEX_ID/expansions?authorization_model_id=$FGA_MODEL_ID" \
  -H "authorization: Bearer $FGA_BEARER_TOKEN"

{
  "error": {
    "code": 123,
    "details": [
      {
        "@type": "<string>"
      }
    ],
    "message": "<string>"
  },
  "result": {
    "closed": {
      "reason": "STREAM_CLOSED_REASON_UNSPECIFIED"
    },
    "event": {
      "as_fresh_as": "2023-11-07T05:31:56Z",
      "from": "<string>",
      "id": "<string>",
      "object_id": "<string>",
      "object_type": "<string>",
      "operation": "EXPANSION_OPERATION_UNSPECIFIED",
      "relation": "<string>",
      "subject_id": "<string>",
      "subject_relation": "<string>",
      "subject_type": "<string>",
      "tuple_written_at": "2023-11-07T05:31:56Z"
    },
    "freshness": {
      "as_fresh_as": "2023-11-07T05:31:56Z"
    },
    "heartbeat": {}
  }
}

{
  "code": "validation_error",
  "message": "Generic validation error"
}

{
  "code": "unauthorized_principal",
  "message": "Missing permissions to perform operation"
}

{
  "code": "unauthorized_principal",
  "message": "Missing permissions to perform operation"
}

{
  "code": "undefined_endpoint",
  "message": "Endpoint not enabled"
}

{
  "code": "10",
  "message": "transaction conflict"
}

{
  "code": "throttled_timeout_error",
  "message": "timeout due to throttling on complex request"
}

{
  "code": "rate_limit_exceeded",
  "message": "Rate Limit exceeded"
}

{
  "code": "internal_error",
  "message": "Internal Server Error"
}

Permissions Index

Stream expansion events from a permissions index

The ReadExpansions API streams pre-computed permission expansion events and index freshness events from a permissions index. Each expansion event represents the addition or removal of a resolved (subject, relation, object) tuple from the indexed FGA relationship. When called without a from cursor, the stream first delivers the full current set of expansion events, then continues emitting events as the underlying index is updated. When resuming a previously-closed stream, clients should provide a from cursor. The ReadExpansions API will resume streaming from that previously checkpointed position, without replaying the full history. Clients must provide the ID of the expected authorization model via the authorization_model_id parameter. In addition to expansion events, the stream emits:

Freshness events indicating how up-to-date the index is at a given point in the stream.
Periodic heartbeat messages to keep the connection alive.
A stream-closed message when the server terminates the connection, including the reason for closure. The server will terminate streams periodically for traffic management. Clients must be prepared to reconnect in order to receive further expansions.

Event deduplication

Each expansion event carries an id field. The same logical event always produces the same id regardless of how many times it is redelivered. Downstream consumers can use this field to deduplicate events.

Examples

Stream all expansions from the beginning

To stream all expansions for index 01YCP46JKYM8FJCQ37NMBYHE5X in store 01G5JAVJ41T49E9TT3SKVS7X1J, call the ReadExpansions API. The stream will emit events like

{
  "result": {
    "event": {
      "id": "051c6d4d930b2810aa92c4711b31629a",
      "from": "eyJpZCI6IjAxWUNQNDZKS1lNOEZKQ1EzN05NQllIRTVYIn0=",
      "subject_type": "user",
      "subject_id": "anne",
      "object_type": "document",
      "object_id": "2021-budget",
      "relation": "viewer",
      "operation": "EXPANSION_OPERATION_INSERT",
      "tuple_written_at": "2026-04-27T17:00:00Z",
      "as_fresh_as": "2026-04-27T17:00:00Z"
    }
  }
}
{
  "result": {
    "freshness": {
      "as_fresh_as": "2026-04-27T17:36:00.282718Z"
    }
  }
}
{
  "result": {
    "heartbeat": {}
  }
}
{
  "result": {
    "closed": {
      "reason": "STREAM_CLOSED_REASON_CONNECTION_LIFETIME_EXCEEDED"
    }
  }
}

Resume a stream from a checkpoint

To resume streaming without replaying events already processed, pass the from cursor returned in the last received event. The stream will pick up from that position.

GET

stores

{store_id}

indexes

{index_id}

expansions

curl

# Set FGA_API_URL to your store region (https://api.us1.fga.dev, or eu1/au1).
# Set FGA_STORE_ID and obtain FGA_BEARER_TOKEN with the client credentials grant.
# See /integration/getting-your-api-keys; never put client secrets in source code.
# Set FGA_MODEL_ID to the authorization model ID.
# Set FGA_INDEX_ID to the permissions index ID.

curl -X GET "$FGA_API_URL/stores/$FGA_STORE_ID/indexes/$FGA_INDEX_ID/expansions?authorization_model_id=$FGA_MODEL_ID" \
  -H "authorization: Bearer $FGA_BEARER_TOKEN"

{
  "error": {
    "code": 123,
    "details": [
      {
        "@type": "<string>"
      }
    ],
    "message": "<string>"
  },
  "result": {
    "closed": {
      "reason": "STREAM_CLOSED_REASON_UNSPECIFIED"
    },
    "event": {
      "as_fresh_as": "2023-11-07T05:31:56Z",
      "from": "<string>",
      "id": "<string>",
      "object_id": "<string>",
      "object_type": "<string>",
      "operation": "EXPANSION_OPERATION_UNSPECIFIED",
      "relation": "<string>",
      "subject_id": "<string>",
      "subject_relation": "<string>",
      "subject_type": "<string>",
      "tuple_written_at": "2023-11-07T05:31:56Z"
    },
    "freshness": {
      "as_fresh_as": "2023-11-07T05:31:56Z"
    },
    "heartbeat": {}
  }
}

{
  "code": "validation_error",
  "message": "Generic validation error"
}

{
  "code": "unauthorized_principal",
  "message": "Missing permissions to perform operation"
}

{
  "code": "unauthorized_principal",
  "message": "Missing permissions to perform operation"
}

{
  "code": "undefined_endpoint",
  "message": "Endpoint not enabled"
}

{
  "code": "10",
  "message": "transaction conflict"
}

{
  "code": "throttled_timeout_error",
  "message": "timeout due to throttling on complex request"
}

{
  "code": "rate_limit_exceeded",
  "message": "Rate Limit exceeded"
}

{
  "code": "internal_error",
  "message": "Internal Server Error"
}

Authorizations

Authorization

string

header

required

The access token received from the authorization server in the OAuth 2.0 flow.

Path Parameters

store_id

string

required

index_id

string

required

Query Parameters

authorization_model_id

string

required

from

string

Optional continuation token for resuming stream

Response

A successful response.(streaming responses)

error

object

Show child attributes

result

Response containing expansion events, heartbeats, or stream closed notifications · object

Show child attributes

Assertions

Authorization Models

Relationship Queries

Relationship Tuples

Permissions Index

Logs

Stream expansion events from a permissions index

Event deduplication

Examples

Stream all expansions from the beginning

Resume a stream from a checkpoint

Authorizations

Path Parameters

Query Parameters

Response