Control API - logs, audit, and usage
Use the FoxIDs Control API to query diagnostic logs, audit events, and usage data, and to configure the log types emitted by an environment. These resources have different purposes and access rights:
- Logs help operators diagnose errors, warnings, protocol flows, events, and metrics.
- Audit records security and administrative actions, including sign-in activity and Control API create, update, and delete requests.
- Usage aggregates activity for operational and billing analysis.
Before calling these operations, configure Control API authentication and access rights. Swagger remains the exact reference for all query parameters, enum values, settings, and response schemas:
Query scope and endpoints
FoxIDs provides three query scopes.
| Scope | Endpoint base | Diagnostic log | Audit | Usage |
|---|---|---|---|---|
| One environment | /api/{tenant_name}/{track_name} |
!tracklog |
!tracklogaudit |
!tracklogusage |
| Your tenant | /api/{tenant_name}/master |
!mytenantlog |
!mytenantlogaudit |
!mytenantlogusage |
| Deployment administration | /api/master/master |
!tenantlog |
!tenantlogaudit |
!tenantlogusage |
Prefix the base with the FoxIDs Control host, for example https://control.foxids.com. Change the host for a self-hosted deployment. Send the access token in the Authorization: Bearer {access_token} header.
Environment queries use the environment from the route. Tenant queries can optionally select an environment with trackName. Deployment-administration queries can select a tenant and environment with tenantName and trackName. The deployment diagnostic query can also include requests rejected before tenant and environment routing.
Use track:log, track:audit, or track:usage access rights, optionally narrowed to a specific environment. Deployment-wide audit and usage require the corresponding master access rights. See the complete access-right tables.
Query diagnostic logs
A diagnostic log request specifies fromTime and toTime as Unix time in seconds. A single request can cover at most 24 hours. Select one or more categories such as errors, warnings, traces, events, and metrics, and use filter for free-text filtering.
A response contains up to 300 of the newest matching entries. Check responseTruncated; when it is true, narrow the time range or filter and query again rather than assuming the result is complete.
Application Insights does not support querying traces and events together through this operation. Send separate requests when both categories are required. Keep time ranges as narrow as practical to improve query performance and reduce the amount of sensitive data returned.
The query endpoints require a searchable primary log repository. They cannot retrieve logs when the deployment's primary log output is standard output (Stdout). In that configuration, query the platform's container or host logging system instead. FoxIDs supports Control queries against configured Application Insights and OpenSearch repositories.
Query audit events
An audit request specifies fromTime and toTime as Unix time in seconds and can cover at most seven days. toTime must be equal to or later than fromTime. The optional filter performs a general free-text search across audit fields and the event data.
A response contains up to 300 of the newest matching audit events. Check responseTruncated and split or narrow the query when a complete result is required.
Audit events include user-facing authentication activity and administrative mutations. Control API POST, PUT, and DELETE actions are audited automatically, while read-only GET requests are not. An audit event can contain useful correlation values such as tenant, environment, authentication method, application, user, session, client IP, and user agent when those values are available for the action.
Audit is designed to show what action occurred and its context. It is not a transactional event queue and should not be used as the sole trigger for business-critical synchronisation. Search results also depend on the configured log repository and retention.
Query usage
Usage requests select a time scope, a UTC offset, and a summarisation level. Include flags determine whether the response contains tenants, environments, authentication methods, users, logins, token requests, additional usage, and Control API activity.
Choose the narrowest scope and only the dimensions needed by the consumer. This keeps responses smaller and avoids exposing tenant or user detail unnecessarily. Use Swagger for the current time-scope and summarisation values.
Configure environment logging
Environment log configuration uses:
| Operation | Endpoint | Purpose |
|---|---|---|
| Get settings | GET /!tracklogsetting |
Read enabled diagnostic log types for the route environment. |
| Save settings | POST /!tracklogsetting |
Replace the environment's log settings. |
| Get streams | GET /!tracklogstreamssettings |
Read external log stream configuration. |
| Save streams | POST /!tracklogstreamssettings |
Replace external log stream configuration. |
The settings control information traces, claim traces, message traces, and metrics. Errors, warnings, critical errors, and events remain available independently as described in Logging. POST replaces the complete settings resource; get the current resource, preserve unchanged properties, and then save the complete representation.
A log stream forwards selected categories to an external destination independently of the primary log repository. This can be used to send a controlled set of environment logs to a separate Application Insights resource.
Claim and message traces can contain personal data, tokens, and complete protocol messages. Enable them only for a defined diagnostic need, restrict access, set an appropriate retention period, and turn them off again when the investigation is complete.
Operational guidance
- Use UTC Unix timestamps in integrations and apply
timeOffsetonly where usage presentation requires a local boundary. - Split long investigations into requests within the endpoint's maximum time range.
- Keep free-text filters specific and avoid relying on display text as a permanent machine identifier.
- Protect returned log and audit data as operationally sensitive information.
- Use audit to investigate and evidence actions, not to replace a guaranteed notification or synchronisation API.
- Expect changes to log settings and streams to be audited because they are Control API mutations.
Common error responses
400 Bad Requestwhen a time range, selector, tenant, environment, or settings resource is invalid.401 Unauthorizedwhen the access token is missing or invalid.403 Forbiddenwhen the caller lacks the required log, audit, or usage access right.404 Not Foundwhen the selected environment or settings resource does not exist.
Use the response body for validation details and Swagger UI for the responses declared by each operation.