# Prepare for an Audit

A client or an auditor asks who can reach their data and what was done with it.
This example shows how to export the answer with a read-only token.

## What the token needs

| Give a workspace token | With the scope |
| - | - |
| The **Auditor** role across every organization | `admin:read` |

The token's access decides what the review covers.
A token with access to part of the tree sees only the members, groups and audit entries inside that part, and no entries that belong to the workspace as a whole.
For a review of the whole workspace, give the role across every organization.

## Export who has access

### 1. Roles

**`GET /workspaces/{workspace_id}/roles`** [List roles](https://sparklogs.com/docs/api/reference/roles.md#list-roles)

Scope: `workspace:read`

```bash
curl -X GET \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/roles" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
```

Response (200)

```json
{
  "message": "roles retrieved",
  "roles": [
    {
      "id": "admin",
      "kind": "standard",
      "description": "Administrator with rights to everything, including managing users in the workspace and their roles",
      "recommended_scope": "all",
      "sort_order": 10,
      "privileges": [
        {
          "id": "workspace.read",
          "level": "self",
          "category": null,
          "access_kind": "view"
        },
        {
          "id": "workspace.write",
          "level": "workspace",
          "category": "organizations",
          "access_kind": "manage"
        },
        {
          "id": "member.read",
          "level": "org",
          "category": "people",
          "access_kind": "view"
        },
        {
          "id": "member.manage",
          "level": "org",
          "category": "people",
          "access_kind": "manage"
        },
        {
          "id": "group.read",
          "level": "org",
          "category": "people",
          "access_kind": "view"
        },
        {
          "id": "group.write",
          "level": "org",
          "category": "people",
          "access_kind": "manage"
        },
        {
          "id": "grant.write",
          "level": "org",
          "category": "people",
          "access_kind": "manage"
        },
        {
          "id": "auditlog.query",
          "level": "org",
          "category": "activity_log",
          "access_kind": "view"
        },
        {
          "id": "organization.read",
          "level": "org",
          "category": "organizations",
          "access_kind": "view"
        },
        {
          "id": "organization.create",
          "level": "org",
          "category": "organizations",
          "access_kind": "manage"
        },
        {
          "id": "organization.write",
          "level": "org",
          "category": "organizations",
          "access_kind": "manage"
        },
        {
          "id": "organization.move",
          "level": "org",
          "category": "organizations",
          "access_kind": "manage"
        },
        {
          "id": "organization.delete",
          "level": "org",
          "category": "organizations",
          "access_kind": "manage"
        },
        {
          "id": "agent.read",
          "level": "org",
          "category": "agents",
          "access_kind": "view"
        },
        {
          "id": "agent.write",
          "level": "org",
          "category": "agents",
          "access_kind": "manage"
        },
        {
          "id": "agent.delete",
          "level": "org",
          "category": "agents",
          "access_kind": "manage"
        },
        {
          "id": "agent_policy.write",
          "level": "org",
          "category": "agents",
          "access_kind": "manage"
        },
        {
          "id": "agent_policy.assign",
          "level": "org",
          "category": "agents",
          "access_kind": "manage"
        },
        {
          "id": "agent_policy.rule_write",
          "level": "org",
          "category": "agents",
          "access_kind": "manage"
        },
        {
          "id": "agent_policy.enforce",
          "level": "org",
          "category": "agents",
          "access_kind": "manage"
        },
        {
          "id": "agent_tag.define",
          "level": "workspace",
          "category": "agents",
          "access_kind": "manage"
        },
        {
          "id": "agent_tag.attach",
          "level": "org",
          "category": "agents",
          "access_kind": "manage"
        },
        {
          "id": "ingest_key.create",
          "level": "org",
          "category": "agents",
          "access_kind": "manage"
        },
        {
          "id": "ingest_key.reveal",
          "level": "org",
          "category": "agents",
          "access_kind": "manage"
        },
        {
          "id": "ingest_key.rotate",
          "level": "org",
          "category": "agents",
          "access_kind": "manage"
        },
        {
          "id": "registration_token.create",
          "level": "org",
          "category": "agents",
          "access_kind": "manage"
        },
        {
          "id": "registration_token.read",
          "level": "org",
          "category": "agents",
          "access_kind": "view"
        },
        {
          "id": "registration_token.reveal",
          "level": "org",
          "category": "agents",
          "access_kind": "manage"
        },
        {
          "id": "registration_token.revoke",
          "level": "org",
          "category": "agents",
          "access_kind": "manage"
        },
        {
          "id": "archive.config.read",
          "level": "org",
          "category": "organizations",
          "access_kind": "view"
        },
        {
          "id": "archive.config.write",
          "level": "org",
          "category": "organizations",
          "access_kind": "manage"
        },
        {
          "id": "event.query",
          "level": "org",
          "category": "event_data",
          "access_kind": "view"
        },
        {
          "id": "device.read",
          "level": "org",
          "category": "event_data",
          "access_kind": "view"
        },
        {
          "id": "event.read",
          "level": "org",
          "category": "raw_logs",
          "access_kind": "view"
        },
        {
          "id": "analytics.query",
          "level": "org",
          "category": "raw_logs",
          "access_kind": "view"
        },
        {
          "id": "ingestion.read",
          "level": "org",
          "category": "billing",
          "access_kind": "view"
        },
        {
          "id": "finance.admin",
          "level": "workspace",
          "category": "billing",
          "access_kind": "manage"
        },
        {
          "id": "user_token.create_own",
          "level": "self",
          "category": null,
          "access_kind": "manage"
        },
        {
          "id": "user_token.manage_own",
          "level": "self",
          "category": null,
          "access_kind": "manage"
        },
        {
          "id": "user_token.view_all",
          "level": "org",
          "category": "people",
          "access_kind": "view"
        },
        {
          "id": "user_token.manage_any",
          "level": "org",
          "category": "people",
          "access_kind": "manage"
        },
        {
          "id": "workspace_token.create",
          "level": "org",
          "category": "people",
          "access_kind": "manage"
        },
        {
          "id": "workspace_token.view",
          "level": "org",
          "category": "people",
          "access_kind": "view"
        },
        {
          "id": "workspace_token.manage",
          "level": "org",
          "category": "people",
          "access_kind": "manage"
        },
        {
          "id": "app_registration.create",
          "level": "workspace",
          "category": "people",
          "access_kind": "manage"
        },
        {
          "id": "app_registration.view",
          "level": "workspace",
          "category": "people",
          "access_kind": "view"
        },
        {
          "id": "app_registration.manage",
          "level": "workspace",
          "category": "people",
          "access_kind": "manage"
        }
      ]
    },
    {
      "id": "organization_admin",
      "kind": "standard",
      "description": "Delegated administrator of its organizations, with no workspace rights",
      "recommended_scope": "selected",
      "sort_order": 20,
      "privileges": [
        {
          "id": "workspace.read",
          "level": "self",
          "category": null,
          "access_kind": "view"
        },
        {
          "id": "member.read",
          "level": "org",
          "category": "people",
          "access_kind": "view"
        },
        {
          "id": "member.manage",
          "level": "org",
          "category": "people",
          "access_kind": "manage"
        },
        {
          "id": "group.read",
          "level": "org",
          "category": "people",
          "access_kind": "view"
        },
        {
          "id": "group.write",
          "level": "org",
          "category": "people",
          "access_kind": "manage"
        },
        {
          "id": "grant.write",
          "level": "org",
          "category": "people",
          "access_kind": "manage"
        },
        {
          "id": "auditlog.query",
          "level": "org",
          "category": "activity_log",
          "access_kind": "view"
        },
        {
          "id": "organization.read",
          "level": "org",
          "category": "organizations",
          "access_kind": "view"
        },
        {
          "id": "organization.create",
          "level": "org",
          "category": "organizations",
          "access_kind": "manage"
        },
        {
          "id": "organization.write",
          "level": "org",
          "category": "organizations",
          "access_kind": "manage"
        },
        {
          "id": "organization.move",
          "level": "org",
          "category": "organizations",
          "access_kind": "manage"
        },
        {
          "id": "organization.delete",
          "level": "org",
          "category": "organizations",
          "access_kind": "manage"
        },
        {
          "id": "agent.read",
          "level": "org",
          "category": "agents",
          "access_kind": "view"
        },
        {
          "id": "agent.write",
          "level": "org",
          "category": "agents",
          "access_kind": "manage"
        },
        {
          "id": "agent.delete",
          "level": "org",
          "category": "agents",
          "access_kind": "manage"
        },
        {
          "id": "agent_policy.write",
          "level": "org",
          "category": "agents",
          "access_kind": "manage"
        },
        {
          "id": "agent_policy.assign",
          "level": "org",
          "category": "agents",
          "access_kind": "manage"
        },
        {
          "id": "agent_policy.rule_write",
          "level": "org",
          "category": "agents",
          "access_kind": "manage"
        },
        {
          "id": "agent_tag.attach",
          "level": "org",
          "category": "agents",
          "access_kind": "manage"
        },
        {
          "id": "ingest_key.create",
          "level": "org",
          "category": "agents",
          "access_kind": "manage"
        },
        {
          "id": "ingest_key.reveal",
          "level": "org",
          "category": "agents",
          "access_kind": "manage"
        },
        {
          "id": "ingest_key.rotate",
          "level": "org",
          "category": "agents",
          "access_kind": "manage"
        },
        {
          "id": "registration_token.create",
          "level": "org",
          "category": "agents",
          "access_kind": "manage"
        },
        {
          "id": "registration_token.read",
          "level": "org",
          "category": "agents",
          "access_kind": "view"
        },
        {
          "id": "registration_token.reveal",
          "level": "org",
          "category": "agents",
          "access_kind": "manage"
        },
        {
          "id": "registration_token.revoke",
          "level": "org",
          "category": "agents",
          "access_kind": "manage"
        },
        {
          "id": "archive.config.read",
          "level": "org",
          "category": "organizations",
          "access_kind": "view"
        },
        {
          "id": "archive.config.write",
          "level": "org",
          "category": "organizations",
          "access_kind": "manage"
        },
        {
          "id": "event.query",
          "level": "org",
          "category": "event_data",
          "access_kind": "view"
        },
        {
          "id": "device.read",
          "level": "org",
          "category": "event_data",
          "access_kind": "view"
        },
        {
          "id": "event.read",
          "level": "org",
          "category": "raw_logs",
          "access_kind": "view"
        },
        {
          "id": "analytics.query",
          "level": "org",
          "category": "raw_logs",
          "access_kind": "view"
        },
        {
          "id": "ingestion.read",
          "level": "org",
          "category": "billing",
          "access_kind": "view"
        },
        {
          "id": "user_token.create_own",
          "level": "self",
          "category": null,
          "access_kind": "manage"
        },
        {
          "id": "user_token.manage_own",
          "level": "self",
          "category": null,
          "access_kind": "manage"
        },
        {
          "id": "user_token.view_all",
          "level": "org",
          "category": "people",
          "access_kind": "view"
        },
        {
          "id": "user_token.manage_any",
          "level": "org",
          "category": "people",
          "access_kind": "manage"
        },
        {
          "id": "workspace_token.create",
          "level": "org",
          "category": "people",
          "access_kind": "manage"
        },
        {
          "id": "workspace_token.view",
          "level": "org",
          "category": "people",
          "access_kind": "view"
        },
        {
          "id": "workspace_token.manage",
          "level": "org",
          "category": "people",
          "access_kind": "manage"
        }
      ]
    },
    {
      "id": "engineer",
      "kind": "standard",
      "description": "Engineer who can fully manage organizations, deploy agents, and query event data",
      "recommended_scope": null,
      "sort_order": 100,
      "privileges": [
        {
          "id": "workspace.read",
          "level": "self",
          "category": null,
          "access_kind": "view"
        },
        {
          "id": "organization.read",
          "level": "org",
          "category": "organizations",
          "access_kind": "view"
        },
        {
          "id": "organization.create",
          "level": "org",
          "category": "organizations",
          "access_kind": "manage"
        },
        {
          "id": "organization.write",
          "level": "org",
          "category": "organizations",
          "access_kind": "manage"
        },
        {
          "id": "organization.delete",
          "level": "org",
          "category": "organizations",
          "access_kind": "manage"
        },
        {
          "id": "agent.read",
          "level": "org",
          "category": "agents",
          "access_kind": "view"
        },
        {
          "id": "agent.write",
          "level": "org",
          "category": "agents",
          "access_kind": "manage"
        },
        {
          "id": "agent.delete",
          "level": "org",
          "category": "agents",
          "access_kind": "manage"
        },
        {
          "id": "ingest_key.create",
          "level": "org",
          "category": "agents",
          "access_kind": "manage"
        },
        {
          "id": "ingest_key.reveal",
          "level": "org",
          "category": "agents",
          "access_kind": "manage"
        },
        {
          "id": "ingest_key.rotate",
          "level": "org",
          "category": "agents",
          "access_kind": "manage"
        },
        {
          "id": "registration_token.create",
          "level": "org",
          "category": "agents",
          "access_kind": "manage"
        },
        {
          "id": "registration_token.read",
          "level": "org",
          "category": "agents",
          "access_kind": "view"
        },
        {
          "id": "registration_token.reveal",
          "level": "org",
          "category": "agents",
          "access_kind": "manage"
        },
        {
          "id": "registration_token.revoke",
          "level": "org",
          "category": "agents",
          "access_kind": "manage"
        },
        {
          "id": "archive.config.read",
          "level": "org",
          "category": "organizations",
          "access_kind": "view"
        },
        {
          "id": "archive.config.write",
          "level": "org",
          "category": "organizations",
          "access_kind": "manage"
        },
        {
          "id": "event.query",
          "level": "org",
          "category": "event_data",
          "access_kind": "view"
        },
        {
          "id": "device.read",
          "level": "org",
          "category": "event_data",
          "access_kind": "view"
        },
        {
          "id": "event.read",
          "level": "org",
          "category": "raw_logs",
          "access_kind": "view"
        },
        {
          "id": "analytics.query",
          "level": "org",
          "category": "raw_logs",
          "access_kind": "view"
        },
        {
          "id": "ingestion.read",
          "level": "org",
          "category": "billing",
          "access_kind": "view"
        },
        {
          "id": "user_token.create_own",
          "level": "self",
          "category": null,
          "access_kind": "manage"
        },
        {
          "id": "user_token.manage_own",
          "level": "self",
          "category": null,
          "access_kind": "manage"
        }
      ]
    },
    {
      "id": "analyst",
      "kind": "standard",
      "description": "Analyst who can only view and query data but not change anything",
      "recommended_scope": null,
      "sort_order": 110,
      "privileges": [
        {
          "id": "workspace.read",
          "level": "self",
          "category": null,
          "access_kind": "view"
        },
        {
          "id": "organization.read",
          "level": "org",
          "category": "organizations",
          "access_kind": "view"
        },
        {
          "id": "agent.read",
          "level": "org",
          "category": "agents",
          "access_kind": "view"
        },
        {
          "id": "archive.config.read",
          "level": "org",
          "category": "organizations",
          "access_kind": "view"
        },
        {
          "id": "event.query",
          "level": "org",
          "category": "event_data",
          "access_kind": "view"
        },
        {
          "id": "device.read",
          "level": "org",
          "category": "event_data",
          "access_kind": "view"
        },
        {
          "id": "event.read",
          "level": "org",
          "category": "raw_logs",
          "access_kind": "view"
        },
        {
          "id": "analytics.query",
          "level": "org",
          "category": "raw_logs",
          "access_kind": "view"
        },
        {
          "id": "ingestion.read",
          "level": "org",
          "category": "billing",
          "access_kind": "view"
        },
        {
          "id": "user_token.create_own",
          "level": "self",
          "category": null,
          "access_kind": "manage"
        },
        {
          "id": "user_token.manage_own",
          "level": "self",
          "category": null,
          "access_kind": "manage"
        }
      ]
    },
    {
      "id": "analyst_no_raw_logs",
      "kind": "standard",
      "description": "Analyst who can query counts, patterns and device health but not raw logs",
      "recommended_scope": null,
      "sort_order": 120,
      "privileges": [
        {
          "id": "workspace.read",
          "level": "self",
          "category": null,
          "access_kind": "view"
        },
        {
          "id": "organization.read",
          "level": "org",
          "category": "organizations",
          "access_kind": "view"
        },
        {
          "id": "agent.read",
          "level": "org",
          "category": "agents",
          "access_kind": "view"
        },
        {
          "id": "archive.config.read",
          "level": "org",
          "category": "organizations",
          "access_kind": "view"
        },
        {
          "id": "event.query",
          "level": "org",
          "category": "event_data",
          "access_kind": "view"
        },
        {
          "id": "device.read",
          "level": "org",
          "category": "event_data",
          "access_kind": "view"
        },
        {
          "id": "ingestion.read",
          "level": "org",
          "category": "billing",
          "access_kind": "view"
        },
        {
          "id": "user_token.create_own",
          "level": "self",
          "category": null,
          "access_kind": "manage"
        },
        {
          "id": "user_token.manage_own",
          "level": "self",
          "category": null,
          "access_kind": "manage"
        }
      ]
    },
    {
      "id": "deployment_manager",
      "kind": "standard",
      "description": "Deploys and manages organizations, agents, agent policy and enrollment, with no data access",
      "recommended_scope": null,
      "sort_order": 130,
      "privileges": [
        {
          "id": "workspace.read",
          "level": "self",
          "category": null,
          "access_kind": "view"
        },
        {
          "id": "organization.read",
          "level": "org",
          "category": "organizations",
          "access_kind": "view"
        },
        {
          "id": "organization.create",
          "level": "org",
          "category": "organizations",
          "access_kind": "manage"
        },
        {
          "id": "organization.write",
          "level": "org",
          "category": "organizations",
          "access_kind": "manage"
        },
        {
          "id": "organization.delete",
          "level": "org",
          "category": "organizations",
          "access_kind": "manage"
        },
        {
          "id": "agent.read",
          "level": "org",
          "category": "agents",
          "access_kind": "view"
        },
        {
          "id": "agent.write",
          "level": "org",
          "category": "agents",
          "access_kind": "manage"
        },
        {
          "id": "agent.delete",
          "level": "org",
          "category": "agents",
          "access_kind": "manage"
        },
        {
          "id": "agent_policy.write",
          "level": "org",
          "category": "agents",
          "access_kind": "manage"
        },
        {
          "id": "agent_policy.assign",
          "level": "org",
          "category": "agents",
          "access_kind": "manage"
        },
        {
          "id": "agent_policy.rule_write",
          "level": "org",
          "category": "agents",
          "access_kind": "manage"
        },
        {
          "id": "agent_tag.attach",
          "level": "org",
          "category": "agents",
          "access_kind": "manage"
        },
        {
          "id": "ingest_key.create",
          "level": "org",
          "category": "agents",
          "access_kind": "manage"
        },
        {
          "id": "ingest_key.reveal",
          "level": "org",
          "category": "agents",
          "access_kind": "manage"
        },
        {
          "id": "ingest_key.rotate",
          "level": "org",
          "category": "agents",
          "access_kind": "manage"
        },
        {
          "id": "registration_token.create",
          "level": "org",
          "category": "agents",
          "access_kind": "manage"
        },
        {
          "id": "registration_token.read",
          "level": "org",
          "category": "agents",
          "access_kind": "view"
        },
        {
          "id": "registration_token.reveal",
          "level": "org",
          "category": "agents",
          "access_kind": "manage"
        },
        {
          "id": "registration_token.revoke",
          "level": "org",
          "category": "agents",
          "access_kind": "manage"
        },
        {
          "id": "user_token.create_own",
          "level": "self",
          "category": null,
          "access_kind": "manage"
        },
        {
          "id": "user_token.manage_own",
          "level": "self",
          "category": null,
          "access_kind": "manage"
        }
      ]
    },
    {
      "id": "auditor",
      "kind": "standard",
      "description": "Reads access and configuration, with no data access",
      "recommended_scope": "all",
      "sort_order": 140,
      "privileges": [
        {
          "id": "workspace.read",
          "level": "self",
          "category": null,
          "access_kind": "view"
        },
        {
          "id": "member.read",
          "level": "org",
          "category": "people",
          "access_kind": "view"
        },
        {
          "id": "group.read",
          "level": "org",
          "category": "people",
          "access_kind": "view"
        },
        {
          "id": "auditlog.query",
          "level": "org",
          "category": "activity_log",
          "access_kind": "view"
        },
        {
          "id": "organization.read",
          "level": "org",
          "category": "organizations",
          "access_kind": "view"
        },
        {
          "id": "agent.read",
          "level": "org",
          "category": "agents",
          "access_kind": "view"
        },
        {
          "id": "registration_token.read",
          "level": "org",
          "category": "agents",
          "access_kind": "view"
        },
        {
          "id": "archive.config.read",
          "level": "org",
          "category": "organizations",
          "access_kind": "view"
        },
        {
          "id": "ingestion.read",
          "level": "org",
          "category": "billing",
          "access_kind": "view"
        },
        {
          "id": "user_token.create_own",
          "level": "self",
          "category": null,
          "access_kind": "manage"
        },
        {
          "id": "user_token.manage_own",
          "level": "self",
          "category": null,
          "access_kind": "manage"
        },
        {
          "id": "user_token.view_all",
          "level": "org",
          "category": "people",
          "access_kind": "view"
        },
        {
          "id": "workspace_token.view",
          "level": "org",
          "category": "people",
          "access_kind": "view"
        },
        {
          "id": "app_registration.view",
          "level": "workspace",
          "category": "people",
          "access_kind": "view"
        }
      ]
    },
    {
      "id": "finance_admin",
      "kind": "standard",
      "description": "Fully manage all financial data and functions, with read access to organizations and no access to event data",
      "recommended_scope": "all",
      "sort_order": 400,
      "privileges": [
        {
          "id": "workspace.read",
          "level": "self",
          "category": null,
          "access_kind": "view"
        },
        {
          "id": "organization.read",
          "level": "org",
          "category": "organizations",
          "access_kind": "view"
        },
        {
          "id": "ingestion.read",
          "level": "org",
          "category": "billing",
          "access_kind": "view"
        },
        {
          "id": "finance.admin",
          "level": "workspace",
          "category": "billing",
          "access_kind": "manage"
        },
        {
          "id": "user_token.create_own",
          "level": "self",
          "category": null,
          "access_kind": "manage"
        },
        {
          "id": "user_token.manage_own",
          "level": "self",
          "category": null,
          "access_kind": "manage"
        }
      ]
    }
  ]
}
```

By default the response lists each role's privileges.
Keep them, to explain what a role id in a grant allows.

### 2. Members and invitations

**`GET /workspaces/{workspace_id}/members`** [List members](https://sparklogs.com/docs/api/reference/members.md#list-members)

Scope: any of `admin:read`, `admin:write`

```bash
curl -X GET \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/members" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
```

Response (200)

```json
{
  "message": "members retrieved",
  "members": [
    {
      "user_id": "AlexRiveraExampleUserId00001",
      "email": "alex.rivera@example.com",
      "full_name": "Alex Rivera",
      "display_name": "Alex",
      "is_self": false,
      "created_at": "2026-11-01T09:00:00Z",
      "deleted_at": null,
      "grants": [
        {
          "id": "6a170000-0000-4000-8000-000000000501",
          "role_id": "admin",
          "scope": {
            "kind": "all",
            "org_ids": [],
            "inherited": false,
            "other_orgs": false
          }
        }
      ],
      "other_grants": false,
      "groups": []
    },
    {
      "user_id": "SamChenExampleUserId00000002",
      "email": "sam.chen@example.com",
      "full_name": "Sam Chen",
      "display_name": "Sam",
      "is_self": false,
      "created_at": "2026-11-02T10:00:00Z",
      "deleted_at": null,
      "grants": [
        {
          "id": "6a170000-0000-4000-8000-000000000502",
          "role_id": "engineer",
          "scope": {
            "kind": "selected",
            "org_ids": [
              "0a9e0000-0000-4000-8000-000000000101"
            ],
            "inherited": false,
            "other_orgs": false
          }
        }
      ],
      "other_grants": false,
      "groups": [
        {
          "id": "9a0b0000-0000-4000-8000-000000000401",
          "name": "Helpdesk Tier 1"
        }
      ]
    }
  ],
  "next_cursor": null
}
```

Each member's entry lists their own grants and the groups they belong to.

**`GET /workspaces/{workspace_id}/invitations`** [List invitations](https://sparklogs.com/docs/api/reference/invitations.md#list-invitations)

Scope: any of `admin:read`, `admin:write`

```bash
curl -X GET \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/invitations" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
```

Response (200)

```json
{
  "message": "invitations retrieved",
  "invitations": [
    {
      "id": "1a7e0000-0000-4000-8000-000000000601",
      "email": "casey.nguyen@example.com",
      "grants": [
        {
          "role_id": "analyst",
          "scope": {
            "kind": "selected",
            "org_ids": [
              "0a9e0000-0000-4000-8000-000000000103"
            ],
            "inherited": false,
            "other_orgs": false
          }
        }
      ],
      "other_grants": false,
      "created_at": "2026-11-08T09:00:00Z",
      "updated_at": "2026-11-08T09:00:00Z",
      "last_sent_at": "2026-11-08T09:00:00Z",
      "expires_at": "2027-02-06T09:00:00Z",
      "invited_by_user_id": "AlexRiveraExampleUserId00001",
      "sender_removed": false
    }
  ],
  "next_cursor": null
}
```

Each pending invitation lists the grants the person holds once they accept.

### 3. Groups

**`GET /workspaces/{workspace_id}/groups`** [List groups](https://sparklogs.com/docs/api/reference/groups.md#list-groups)

Scope: any of `admin:read`, `admin:write`

With `members` named in `fields`.

```bash
curl -X GET \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/groups?fields=id%2Cname%2Ccreated_at%2Cupdated_at%2Cgrants%2Cother_grants%2Cmember_count%2Cmembers" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
```

Response (200)

```json
{
  "groups": [
    {
      "id": "9a0b0000-0000-4000-8000-000000000401",
      "name": "Helpdesk Tier 1",
      "created_at": "2026-11-02T10:00:00Z",
      "updated_at": "2026-11-02T10:00:00Z",
      "grants": [
        {
          "id": "6a170000-0000-4000-8000-000000000503",
          "role_id": "analyst_no_raw_logs",
          "scope": {
            "kind": "selected",
            "org_ids": [
              "0a9e0000-0000-4000-8000-000000000101",
              "0a9e0000-0000-4000-8000-000000000105"
            ],
            "inherited": false,
            "other_orgs": false
          }
        }
      ],
      "other_grants": false,
      "member_count": 1,
      "members": [
        {
          "user_id": "SamChenExampleUserId00000002",
          "email": "sam.chen@example.com",
          "full_name": "Sam Chen",
          "display_name": "Sam"
        }
      ]
    },
    {
      "id": "9a0b0000-0000-4000-8000-000000000402",
      "name": "Project Engineers",
      "created_at": "2026-11-02T10:00:00Z",
      "updated_at": "2026-11-02T10:00:00Z",
      "grants": [
        {
          "id": "6a170000-0000-4000-8000-000000000505",
          "role_id": "engineer",
          "scope": {
            "kind": "selected",
            "org_ids": [
              "0a9e0000-0000-4000-8000-000000000103"
            ],
            "inherited": false,
            "other_orgs": false
          }
        }
      ],
      "other_grants": false,
      "member_count": 0,
      "members": []
    }
  ],
  "message": "workspace groups retrieved",
  "next_cursor": null
}
```

Pass `fields` with `members` added to the default fields.
Each group's entry then lists its grants and its members, so one paged call covers every group.

### 4. Organizations

**`GET /workspaces/{workspace_id}/organizations`** [List organizations](https://sparklogs.com/docs/api/reference/organizations.md#list-organizations)

Scope: `workspace:read`

Pass `deleted=include`, so that a grant naming a deleted organization can still be explained. Page to the end with `cursor`.

```bash
curl -X GET \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/organizations?deleted=include" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
```

Response (200)

```json
{
  "message": "organizations retrieved",
  "next_cursor": null,
  "organizations": [
    {
      "id": "0a9e0000-0000-4000-8000-000000000100",
      "parent_id": null,
      "path": [
        "0a9e0000-0000-4000-8000-000000000100"
      ],
      "name": "Northwind clients",
      "description": "Every client of Northwind IT Services",
      "rmm_client_id": null,
      "psa_client_id": null,
      "created_at": "2026-11-01T09:00:00Z",
      "updated_at": "2026-11-01T09:00:00Z",
      "deleted_at": null
    },
    {
      "id": "0a9e0000-0000-4000-8000-000000000101",
      "parent_id": "0a9e0000-0000-4000-8000-000000000100",
      "path": [
        "0a9e0000-0000-4000-8000-000000000100",
        "0a9e0000-0000-4000-8000-000000000101"
      ],
      "name": "Lakeside Clinic",
      "description": "Family practice, two sites",
      "rmm_client_id": "LAKESIDE-01",
      "psa_client_id": "10042",
      "created_at": "2026-11-02T09:00:00Z",
      "updated_at": "2026-11-02T09:00:00Z",
      "deleted_at": null
    },
    {
      "id": "0a9e0000-0000-4000-8000-000000000102",
      "parent_id": "0a9e0000-0000-4000-8000-000000000101",
      "path": [
        "0a9e0000-0000-4000-8000-000000000100",
        "0a9e0000-0000-4000-8000-000000000101",
        "0a9e0000-0000-4000-8000-000000000102"
      ],
      "name": "Finance",
      "description": null,
      "rmm_client_id": null,
      "psa_client_id": null,
      "created_at": "2026-11-03T10:00:00Z",
      "updated_at": "2026-11-03T10:00:00Z",
      "deleted_at": null
    },
    {
      "id": "0a9e0000-0000-4000-8000-000000000103",
      "parent_id": "0a9e0000-0000-4000-8000-000000000100",
      "path": [
        "0a9e0000-0000-4000-8000-000000000100",
        "0a9e0000-0000-4000-8000-000000000103"
      ],
      "name": "Oakridge Medical",
      "description": null,
      "rmm_client_id": "OAKRIDGE-01",
      "psa_client_id": null,
      "created_at": "2026-11-02T09:00:00Z",
      "updated_at": "2026-11-04T11:00:00Z",
      "deleted_at": null
    },
    {
      "id": "0a9e0000-0000-4000-8000-000000000104",
      "parent_id": "0a9e0000-0000-4000-8000-000000000100",
      "path": [
        "0a9e0000-0000-4000-8000-000000000100",
        "0a9e0000-0000-4000-8000-000000000104"
      ],
      "name": "Summit Accounting",
      "description": null,
      "rmm_client_id": null,
      "psa_client_id": null,
      "created_at": "2026-11-02T09:00:00Z",
      "updated_at": "2026-11-06T14:00:00Z",
      "deleted_at": "2026-11-06T14:00:00Z"
    },
    {
      "id": "0a9e0000-0000-4000-8000-000000000105",
      "parent_id": "0a9e0000-0000-4000-8000-000000000100",
      "path": [
        "0a9e0000-0000-4000-8000-000000000100",
        "0a9e0000-0000-4000-8000-000000000105"
      ],
      "name": "Harbor Dental",
      "description": null,
      "rmm_client_id": null,
      "psa_client_id": "10057",
      "created_at": "2026-11-02T09:00:00Z",
      "updated_at": "2026-11-09T16:00:00Z",
      "deleted_at": null
    }
  ],
  "watermark": "2026-11-10T09:00:00Z"
}
```

### Combine the lists

A person's access is their own grants plus the grants of every group they are in.
Each grant is a role over every organization, over a list of organizations and everything below each, or over the workspace itself.
Join the lists of roles, members, groups and organizations on `user_id`, group `id`, `role_id` and organization `id`.
The result shows, for each person, each role they hold and the organizations it covers.

## Export the audit log

**`GET /workspaces/{workspace_id}/audit-events`** [List audit events](https://sparklogs.com/docs/api/reference/audit-events.md#list-audit-events)

Scope: any of `admin:read`, `admin:write`

Pass `occurred_since` and `occurred_before` for the period, and page with `cursor`. Entries come newest first, 500 a page by default and up to 5,000 with `limit`.

```bash
curl -X GET \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/audit-events?credential_id=4b1d0000-0000-4000-8000-000000000801&occurred_since=2026-10-11T00%3A00%3A00Z&limit=1" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
```

Response (200)

```json
{
  "message": "audit events retrieved",
  "audit_events": [
    {
      "id": "ad170000-0000-4000-8000-000000000701",
      "occurred_at": "2026-11-09T16:00:00Z",
      "last_occurred_at": "2026-11-09T16:00:00Z",
      "occurrences": 1,
      "actor_kind": "workspace_key",
      "actor_id": "4b1d0000-0000-4000-8000-000000000801",
      "actor_desc": null,
      "credential_kind": "workspace_key",
      "credential_id": "4b1d0000-0000-4000-8000-000000000801",
      "action": "organization.update",
      "privileges": [
        "organization.write"
      ],
      "target_kind": "organization",
      "target_id": "0a9e0000-0000-4000-8000-000000000105",
      "target_desc": "Harbor Dental",
      "org_ids": [
        "0a9e0000-0000-4000-8000-000000000105"
      ],
      "all_orgs": false,
      "outcome": "allowed",
      "reason": null,
      "details": {
        "changes": [
          {
            "field": "psa_client_id",
            "new": "10057",
            "old": null
          }
        ]
      },
      "details_v": 1,
      "ip": "203.0.113.24",
      "user_agent": "psa-sync/2.3",
      "invocation_method": "direct"
    }
  ],
  "next_cursor": "eyJ2IjoxLCJleGFtcGxlIjoiYXVkaXQifQ"
}
```

The next page takes the `next_cursor` of the one before, with the same filters:

**`GET /workspaces/{workspace_id}/audit-events`** [List audit events](https://sparklogs.com/docs/api/reference/audit-events.md#list-audit-events)

Scope: any of `admin:read`, `admin:write`

```bash
curl -X GET \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/audit-events?credential_id=4b1d0000-0000-4000-8000-000000000801&occurred_since=2026-10-11T00%3A00%3A00Z&limit=1&cursor=eyJ2IjoxLCJleGFtcGxlIjoiYXVkaXQifQ" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
```

Response (200)

```json
{
  "message": "audit events retrieved",
  "audit_events": [
    {
      "id": "ad170000-0000-4000-8000-000000000702",
      "occurred_at": "2026-11-03T10:00:00Z",
      "last_occurred_at": "2026-11-03T10:00:00Z",
      "occurrences": 1,
      "actor_kind": "workspace_key",
      "actor_id": "4b1d0000-0000-4000-8000-000000000801",
      "actor_desc": null,
      "credential_kind": "workspace_key",
      "credential_id": "4b1d0000-0000-4000-8000-000000000801",
      "action": "organization.create",
      "privileges": [
        "organization.create"
      ],
      "target_kind": "organization",
      "target_id": "0a9e0000-0000-4000-8000-000000000102",
      "target_desc": "Finance",
      "org_ids": [
        "0a9e0000-0000-4000-8000-000000000101",
        "0a9e0000-0000-4000-8000-000000000102"
      ],
      "all_orgs": false,
      "outcome": "allowed",
      "reason": null,
      "details": {
        "name": "Finance",
        "parent_id": "0a9e0000-0000-4000-8000-000000000101"
      },
      "details_v": 1,
      "ip": "203.0.113.24",
      "user_agent": "psa-sync/2.3",
      "invocation_method": "direct"
    }
  ],
  "next_cursor": null
}
```

Useful filters:

| Filter | Shows |
| - | - |
| `actor_id` | Everything one person did. |
| `credential_id` | Everything one API token or connected app did. |
| `organization_id` | Everything that touched one client. |
| `target_id` | Everything done to one thing, such as one agent, group or member. |
| `action_prefix` | One kind of action, such as `grant` for access changes. Token changes are under three prefixes: `user_token.` and `workspace_token.` for a create, and `token.` for every later change. Each call's reference page gives the action it is recorded under. |
| `outcome` | Entries with one outcome, such as refused attempts. |
| `invocation_method` | `mcp` for what an AI app or other MCP client did, `direct` for everything else. |

For what is recorded, see [Audit logs](https://sparklogs.com/docs/workspace/audit-logs.md).

Repeated refusals of the same kind are folded into one entry with a count in `occurrences`.
A folded entry is dated by its first occurrence, so a period that starts after that date leaves the entry out, even when repeats fall inside the period.
To catch those, start the period earlier and filter on `last_occurred_at` in your own code.

## What the API does not do

- It does not list API tokens or connected apps. Review those in the app, on the **Access** tab. The audit log shows when each was created or changed, and every audited call carries the `credential_id` of the token that made it.
- It does not show a workspace token's grants.
- It does not compute a person's combined access. Combine the lists as shown above.

---

Source: <https://sparklogs.com/docs/api/use-cases/access-review>
All SparkLogs documentation in Markdown: <https://sparklogs.com/llms.txt>
