Skip to main content

Overview

The Auth0 Fine-Grained Authorization (FGA) Logs enable users to query access logs that capture all operations across all Auth0 FGA public endpoints. These logs help with:
  • Security: Identify who made changes to permissions.
  • Monitoring and compliance: Ensure authorization policies behave as expected.
  • Operational analysis: Inspect recent API activity to troubleshoot and optimize your implementation.

Key Features

  • Log Retention: Logs are retained for 7 days.
  • Rate-Limits by tier:
    • Free: 1 RPS
    • Enterprise: 8 RPS
  • Access methods:
    • Dashboard: View, filter, and search logs through the dashboard interface.
    • API: Programmatic retrieval of logs for integration with external analytics tools. To retrieve logs, your API token must have the Search logs permission set enabled via the FGA Management Dashboard (see screenshot below). Logs are retrieved using the same authentication mechanism as other FGA APIs.
Image showing the search logs store client scope

View Logs in the Dashboard

The Logs section in the FGA Management Dashboard allows you to inspect your store activity, enabling you to search and filter logs without manual API calls. The search box in the Dashboard supports the same Lucene query syntax as the API’s query parameter, so you can use any of the query patterns documented below.
  1. Navigate to your Store in the FGA Dashboard.
  2. Select Logs from the left-hand sidebar.
  3. Use the search box to filter logs using query syntax (e.g., request.operation:"Write"), and/or use the date range picker to constrain results.
  4. Select any log entry to view the full details in the right-hand panel, including all request fields, response metadata, and the raw JSON payload. This is a convenient way to discover queryable field names for each operation type.
Image showing logs in Dashboard

Logging API

The Logging API is designed to provide authorization activity in a standardized format for developers, platform engineers, and compliance teams.

Log schema

Each log entry captures request metadata, response details, and operation-specific payload. Below is a sample for the Write() endpoint:
All FGA API operations are logged and follow the same general structure, with operation-specific payload fields. For example, Write logs include request.writes and request.deletes arrays, while Check logs include request.tuple_key fields.

Supported Query Parameters

The Auth0 FGA Logging API allows you to filter and retrieve logs using a set of query parameters. These parameters enable you to narrow down your search and analyze log data efficiently.

Log Search Query Syntax

When searching for logs, you can create queries using a subset of Lucene query syntax to refine your search.
  • A term can be a single word such as jane or smith.
  • A term can be a phrase in single quotes (‘customer log’).
  • Multiple terms can be grouped with parentheses to form sub-queries.
  • All search fields are case sensitive.
  • Operators (AND, OR, NOT) work on all searchable fields.

Supported Operations

The request.operation field identifies the API operation that generated the log entry. The following values are valid: Each operation type has its own schema. Some fields are shared across all operations (such as request.id, request.client_id, and response.status_code), while others are specific to an operation (such as request.writes for Write or request.tuple_key for Check).

Common Searchable Fields

The following fields are shared across all or most log entries and can be used in queries: Request metadata: Contextual headers (set by the caller): Operation-specific fields (examples): Response and other fields:
Discovering additional fieldsThis is not an exhaustive list. Each operation may include additional fields specific to its request and response schema. To discover all available fields for a given operation:
  1. Filter logs by operation — via the API (query=request.operation:Check) or the Dashboard search box.
  2. Inspect the returned log entries, or click a log row in the Dashboard to view the full details panel and raw JSON payload.
  3. Use the field paths you find (e.g., request.tuple_key.object) to build more specific queries.

Query Examples

To retrieve logs, send a GET request to the /stores/{store_id}/logs endpoint.

Before you begin:

  1. Obtain your API token to call the Logging API.
  2. Set environment variables:

Examples:

  1. Use defaults (last 7 days to now)
  1. Filter by Time Range
  1. Filter by Operation
  1. Filter by Tuple keys (user value)
  1. Paginate results
  • First page (optionally constrain the window and page size):
  • Next page (use the continuation_token returned from the previous response):
Note: When passing a continuation_token along with start_time, the continuation_token takes precedence.
  1. Retrieve results in descending order (most recent first):
Note: When passing a continuation_token along with sort, the continuation_token takes precedence.
  1. Combine conditions with AND
  1. Exclude results with -
  1. Filter by response status code
  1. Filter by client ID
  1. Filter by actor

Setting Contextual Parameters as Headers

You can pass optional contextual headers with each request to provide richer traceability and auditing context:
  • Actor ID (X-FGA-Actor-ID): Identifies the user or service principal initiating the API request that could affect authorization data. Example: "X-FGA-Actor-ID": "user-123" or "X-FGA-Actor-ID": "service-account-billing-job".
  • IP Address (X-FGA-Forwarded-For): Captures the originating IP address of the actor making the request. Example: "X-FGA-Forwarded-For": "192.123.1.1".
  • Correlation ID (X-Correlation-ID): A unique identifier provided by the calling application to track a single logical operation across multiple services or requests. Example: "X-Correlation-ID": "abc234-dfg345-jhk3"
These values are captured in the Logging API schema under:
  • X-FGA-Actor-ID → request.actor_id
  • X-FGA-Forwarded-For → request.actor_ip
  • X-Correlation-ID → request.correlation_id
Below is a reference code snippet showing how to pass these headers: The Logging API won’t have CLI or SDK support; you should use direct REST calls to call this API.

Export Logs to External Systems

You can build automated scripts to export FGA logs to external data sinks for long-term storage, analytics, or compliance purposes. The examples below demonstrate polling the Logging API and saving logs to local files in JSONL format. Important considerations:
  • The polling frequency in these examples is set to 1 hour - adjust this based on your use case and rate limits
  • Consider your tier’s rate limits when setting polling intervals (Free: 1 RPS, Enterprise: 8 RPS)
  • Logs are retained for 7 days, so ensure your export frequency captures all necessary data
  • Each example handles pagination using continuation tokens to retrieve all available logs