Audit Logs

Sphere maintains an immutable audit trail of all significant actions across the platform. Every entity change, user action, and system event is recorded with full context including the actor, target, metadata, and correlation ID. Audit entries cannot be modified or deleted.

The audit entry model

Each audit entry captures a single action performed by an actor on a target resource.

Properties

Name
id
Type
string (UUID)
Description
Unique identifier for the audit entry.
Name
action
Type
string
Description
The action that was performed (e.g., entity.created, entity.updated, entity.deleted, user.login, workflow.executed).
Name
actor_id
Type
string (UUID)
Description
The ID of the actor who performed the action.
Name
actor_type
Type
string
Description
The type of actor: user, system, workflow, or service.
Name
target_type
Type
string
Description
The type of the target resource (e.g., entity, user, workflow, workspace).
Name
target_id
Type
string (UUID)
Description
The ID of the target resource.
Name
metadata
Type
object
Description
Additional context about the action. Contents vary by action type and may include changed fields, old/new values, or request details.
Name
correlation_id
Type
string (UUID)
Description
A shared identifier linking related audit entries across a single operation or request chain.
Name
ip_address
Type
string
Description
The IP address from which the action was performed. Null for system or service actions.
Name
created_at
Type
string (ISO 8601)
Description
Timestamp when the action was recorded.

Audit entries are immutable. There are no update or delete endpoints. This ensures the audit trail is a reliable, tamper-proof record of all platform activity.

GET/core/api/v1/audit

List audit entries

Retrieve a paginated list of audit entries for the current tenant. Results are ordered by creation date descending (most recent first). Use query parameters to filter by action, actor, date range, or target.

Query parameters

Name
action
Type
string
Description
Filter by action type (e.g., entity.created, user.login).
Name
actor_id
Type
string (UUID)
Description
Filter by the actor who performed the action.
Name
actor_type
Type
string
Description
Filter by actor type: user, system, workflow, or service.
Name
from_date
Type
string (ISO 8601)
Description
Return entries created on or after this date.
Name
to_date
Type
string (ISO 8601)
Description
Return entries created on or before this date.
Name
page
Type
integer
Description
Page number for pagination. Default is 1.
Name
per_page
Type
integer
Description
Number of entries per page. Default is 50, maximum is 100.

Request

GET

/core/api/v1/audit

curl -G https://your-sphere.example.com/core/api/v1/audit \
  -H "Authorization: Bearer {access_token}" \
  -d action=entity.created \
  -d from_date=2026-01-01T00:00:00Z \
  -d per_page=25

Response

{
  "data": [
    {
      "id": "a1b2c3d4-5678-9012-abcd-ef0123456789",
      "action": "entity.created",
      "actor_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "actor_type": "user",
      "target_type": "entity",
      "target_id": "c3d4e5f6-7890-1234-abcd-567890abcdef",
      "metadata": {
        "family_code": "contacts",
        "entity_name": "John Doe"
      },
      "correlation_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "ip_address": "192.168.1.100",
      "created_at": "2026-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total": 142
  }
}

GET/core/api/v1/audit/{id}

Get audit entry

Retrieve the full details of a specific audit entry by its ID. This includes the complete metadata object with all recorded context.

Request

GET

/core/api/v1/audit/{id}

curl https://your-sphere.example.com/core/api/v1/audit/a1b2c3d4-5678-9012-abcd-ef0123456789 \
  -H "Authorization: Bearer {access_token}"

Response

{
  "data": {
    "id": "a1b2c3d4-5678-9012-abcd-ef0123456789",
    "action": "entity.created",
    "actor_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "actor_type": "user",
    "target_type": "entity",
    "target_id": "c3d4e5f6-7890-1234-abcd-567890abcdef",
    "metadata": {
      "family_code": "contacts",
      "entity_name": "John Doe",
      "fields": {
        "email": "john.doe@example.com",
        "phone": "+33612345678"
      }
    },
    "correlation_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "ip_address": "192.168.1.100",
    "created_at": "2026-01-15T10:30:00Z"
  }
}

GET/core/api/v1/audit/target/{type}/{id}

Get target history

Retrieve the complete audit history for a specific entity or resource. This returns all audit entries where the given type and ID match the target, ordered chronologically. Use this to see every action that has been performed on a specific resource.

Path parameters

Name
type
Type
string
Description
The target type to query (e.g., entity, user, workflow, workspace).
Name
id
Type
string (UUID)
Description
The target resource ID.

Request

GET

/core/api/v1/audit/target/{type}/{id}

curl https://your-sphere.example.com/core/api/v1/audit/target/entity/c3d4e5f6-7890-1234-abcd-567890abcdef \
  -H "Authorization: Bearer {access_token}"

Response

{
  "data": [
    {
      "id": "a1b2c3d4-5678-9012-abcd-ef0123456789",
      "action": "entity.created",
      "actor_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "actor_type": "user",
      "target_type": "entity",
      "target_id": "c3d4e5f6-7890-1234-abcd-567890abcdef",
      "metadata": {
        "family_code": "contacts",
        "entity_name": "John Doe"
      },
      "correlation_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "ip_address": "192.168.1.100",
      "created_at": "2026-01-15T10:30:00Z"
    },
    {
      "id": "b2c3d4e5-6789-0123-bcde-f01234567890",
      "action": "entity.updated",
      "actor_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "actor_type": "user",
      "target_type": "entity",
      "target_id": "c3d4e5f6-7890-1234-abcd-567890abcdef",
      "metadata": {
        "changed_fields": ["email"],
        "old_values": { "email": "john@old.com" },
        "new_values": { "email": "john.doe@example.com" }
      },
      "correlation_id": "e8b2c5a1-9f3d-4e7b-8c6a-1d2e3f4a5b6c",
      "ip_address": "192.168.1.100",
      "created_at": "2026-01-16T08:15:30Z"
    }
  ]
}