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 logspermission set enabled via the FGA Management Dashboard (see screenshot below). Logs are retrieved using the same authentication mechanism as other FGA APIs.
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’squery parameter, so you can use any of the query patterns documented below.
- Navigate to your Store in the FGA Dashboard.
- Select Logs from the left-hand sidebar.
- 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. - 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.
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 theWrite() endpoint:
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
Therequest.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:
Query Examples
To retrieve logs, send a GET request to the/stores/{store_id}/logs endpoint.
Before you begin:
- Obtain your API token to call the Logging API.
- Set environment variables:
Examples:
- Use defaults (last 7 days to now)
- Filter by Time Range
- Filter by Operation
- Filter by Tuple keys (user value)
- Paginate results
- First page (optionally constrain the window and page size):
- Next page (use the
continuation_tokenreturned from the previous response):
Note: When passing acontinuation_tokenalong withstart_time, thecontinuation_tokentakes precedence.
- Retrieve results in descending order (most recent first):
Note: When passing acontinuation_tokenalong withsort, thecontinuation_tokentakes precedence.
- Combine conditions with AND
- Exclude results with
-
- Filter by response status code
- Filter by client ID
- 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"
-
X-FGA-Actor-ID→request.actor_id -
X-FGA-Forwarded-For→request.actor_ip -
X-Correlation-ID→request.correlation_id
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
- Node.js
- Python
- .NET
- Java
- Go
- curl