Skip to main content

Getting Started

Overview​

  • Portal Audit Logs is a standardized logging and event-capture system that records critical user-initiated actions (e.g., role assignments, config changes, template runs, etc.).
  • This feature allows platform and security teams to trace activity across Portal to satisfy compliance requirements, while providing a clear, queryable event trail to simplify support and troubleshooting.
  • Portal Audit Logs is built on top of Backstage’s Auditor Core Service and exposed via REST API.

API Quick Start​

Use the Audit Log REST API to access audit events with different filters.

  1. Ask your admin for the audit log API token. If a token hasn't been set up yet, an admin should follow the Set the API token guide first.
  2. To fetch audit events, call the API with the following endpoint and header. See example requests below.
GET /api/audit-log/v1/audit-event
Authorization: Bearer <your-secure-token-here>

Example requests​

Note: For full request specifications, see the API Request Parameters reference.

Get medium severity events from the Catalog plugin, with a limit of 10:

curl -H "Authorization: Bearer your-secure-token-here" \ "https://your-portal.com/api/audit-log/v1/audit-event?plugin_id=catalog&severity_level=medium&limit=10"

Get failed events in a specific time range:

curl -H "Authorization: Bearer your-secure-token-here" \ "https://your-portal.com/api/audit-log/v1/audit-event?status=failed&start_time=2026-01-01T00:00:00Z&end_time=2026-01-31T23:59:59Z"

Get events for a specific event with pagination:

curl -H "Authorization: Bearer your-secure-token-here" \ "https://your-portal.com/api/audit-log/v1/audit-event?event_id=entity-fetch&limit=10&offset=1"

Example response​

Note: For full response specifications, see the API Response Fields reference.

The API returns a JSON object with the following structure below. Results are ordered by event_time in descending order (newest first).

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "event_time": "2025-01-15T12:00:00.000Z",
      "recorded_at": "2025-01-15T12:00:01.000Z",
      "plugin_id": "catalog",
      "event_id": "entity.created",
      "severity_level": "high",
      "status": "succeeded",
      "actor_type": "user",
      "actor_id": "user:default/john",
      "request_method": "POST",
      "request_url": "/api/catalog/entities",
      "action_type": "create",
      "query_type": "mutation",
      "entity_ref": "component:default/my-service",
      "meta": {
        "description": "Created new service component"
      }
    }
  ],
  "total": 150,
  "limit": 100,
  "offset": 0
}