History

This page explains how to search history events and provides a reference for all recorded actions.

History entries

The system records most events involving the following entities:

• Credentials
• Proofs
• Keys
• Identifiers
• Certificates
• DIDs
• Schemas
• Organizations
• Trust anchors
• Trust entities
• Wallet units
• Wallet unit attestations
• Wallet relying parties
• Backups (in the mobile SDK)
• OpenID providers in OpenID Bridge
• Users
• STS roles, organizations, IAM roles, and tokens

Each event is represented by a history entry containing:

• The entity UUID, name, and type
• The action or event that took place
• The source service that recorded the event
• Metadata about the event

Here's a history entry of a wallet unit revocation:

{
  "id": "3cb2384a-1198-4af3-b4c2-0a32bbd4deef",       // UUID of the event
  "createdDate": "2025-11-25T14:31:00.066Z",          // Datetime of the event
  "source": "CORE",                                   // Service that recorded the event
  "action": "REVOKED",                                // What happened
  "name": "PROCIVIS_ONE-WEB-1764081045",              // Name of the entity
  "entityType": "WALLET_UNIT",                        // The type of entity
  "entityId": "401602e7-13ce-440b-a406-4d2d3dc91c34", // UUID of the entity
  "organisation": {                                   // The organization the entity belongs to
    "name": "Admin",
    "id": "6a9275e4-8a28-4170-b79c-ee48c749f4a9"
  },
  "target": "401602e7-13ce-440b-a406-4d2d3dc91c34"    // Related entity (context-dependent)
}

note

The history entry does not express an entity's current state, but rather a historical event, named in the action field.

Name

For most entities, the name field of the history entry is the entity name. There are two exceptions:

• Credentials: for all history events of a credential, this field provides the name of the credential schema.
• Proofs: for all history events of a proof, this field provides the name of the proof schema.

Target

For proofs and credentials, the target field provides the identifier UUID of the external participant in the interaction, if available:

	System is issuer	System is holder	System is verifier
Credential	Holder identifier	Issuer identifier
Proof		Verifier identifier	Holder identifier

How to search history

The history endpoint provides several methods for searching and filtering history events. Each method can be used alone or in conjuction with other methods.

History operations

Core API | Desk API

By time frame

You can retrieve history events within a particular time frame by setting a start time, a stop time, or both. Use:

• createdDateAfter to set a start time.
• createdDateBefore to set a stop time.

Here's an example curl query to retrieve all events since a datetime:

-X 'GET' \
  'https://{{example.com}}/api/history/v1?page=0&pageSize=999&createdDateAfter=2025-03-05T14%3A19%3A57.000Z&organisationId={{UUID}}' \

Since there is no createdDateBefore, this call will retrieve all events that have occurred from the specified time up to the time you query the history endpoint.

By schema ID

You can retrieve history events associated with a particular schema. This includes not only schema events but also the events of credentials and proofs created using the schema. Use:

• credentialSchemaId for credential schemas.
• proofSchemaId for proof schemas.

Here's an example curl query to retrieve events for a credential schema:

-X 'GET' \
  'https://{{example.com}}/api/history/v1?page=0&pageSize=999&credentialSchemaId={{UUID}}&organisationId={{UUID}}' \

And here's the response:

{
  "values": [
    {
      "id": "8dc94bdd-7b00-4f20-b154-1ae36b4e01a4",
      "createdDate": "2025-03-06T08:25:52.620Z",
      "action": "ACCEPTED",
      "entityId": "936bac3e-f9ed-4ce6-bae0-a1a6ba115d7a",
      "entityType": "CREDENTIAL",
      "name": "Driver's License",
      "organisationId": "2476ebaa-0108-413d-aa72-c2a6babd423f",
      "target": "did:key:z6MkiggrQ3WBydSo1FnEw38GPQ1upwk8hW5tHGecaFDQEzdP"
    },
    {
      "id": "88e00dd1-ef16-4925-a00e-d1a82267e1aa",
      "createdDate": "2025-03-06T08:25:51.099Z",
      "action": "OFFERED",
      "entityId": "936bac3e-f9ed-4ce6-bae0-a1a6ba115d7a",
      "entityType": "CREDENTIAL",
      "name": "Driver's License",
      "organisationId": "2476ebaa-0108-413d-aa72-c2a6babd423f"
    },
    {
      "id": "db88c2c1-47b9-4320-bedb-cd8278baf17f",
      "createdDate": "2025-03-06T08:25:44.768Z",
      "action": "SHARED",
      "entityId": "936bac3e-f9ed-4ce6-bae0-a1a6ba115d7a",
      "entityType": "CREDENTIAL",
      "name": "Driver's License",
      "organisationId": "2476ebaa-0108-413d-aa72-c2a6babd423f"
    },
    {
      "id": "bb5756f2-f87c-482d-a9b2-673712f12214",
      "createdDate": "2025-03-06T08:25:44.753Z",
      "action": "PENDING",
      "entityId": "936bac3e-f9ed-4ce6-bae0-a1a6ba115d7a",
      "entityType": "CREDENTIAL",
      "name": "Driver's License",
      "organisationId": "2476ebaa-0108-413d-aa72-c2a6babd423f"
    },
    {
      "id": "ce5bc098-c43d-47f8-b73a-0c86c42ea5e0",
      "createdDate": "2025-03-06T08:25:44.619Z",
      "action": "CREATED",
      "entityId": "936bac3e-f9ed-4ce6-bae0-a1a6ba115d7a",
      "entityType": "CREDENTIAL",
      "name": "Driver's License",
      "organisationId": "2476ebaa-0108-413d-aa72-c2a6babd423f"
    },
    {
      "id": "0e1917f1-a7db-441e-a3f4-537dcd4862a9",
      "createdDate": "2025-03-06T08:25:29.826Z",
      "action": "CREATED",
      "entityId": "3f526536-a118-4247-a3c4-69f86c1052d3",
      "entityType": "CREDENTIAL_SCHEMA",
      "name": "Driver's License",
      "organisationId": "2476ebaa-0108-413d-aa72-c2a6babd423f"
    }
  ],
  "totalPages": 1,
  "totalItems": 6
}

In the response we see events for the schema and for any credential that was created using the schema.

By action

You can retrieve history events of particular event types. Use:

• actions[] to specify which kind(s) of event.

Here's an example curl query to retrieve all suspension and revocation events:

-X 'GET' \
  'https://{{example.com}}/api/history/v1?page=0&pageSize=999&actions%5B%5D=SUSPENDED&actions%5B%5D=REVOKED&organisationId={{UUID}}' \

The full reference for actions is found in: What's recorded.

By entity type

You can retrieve history events of particular entity types. Use:

• entityTypes[] to specify which kind(s) of entity.

Here's an example curl query to retrieve all history events for credential schemas and proof schemas:

-X 'GET' \
  'https://{{example.com}}/api/history/v1?page=0&pageSize=999&entityTypes%5B%5D=CREDENTIAL_SCHEMA&entityTypes%5B%5D=PROOF_SCHEMA&organisationId={{UUID}}' \

By entity ID

You can retrieve history entries for particular entities. Use:

• entityIds[] to specify which entity or entities.

Here's an example curl query to retrieve all history events for two credentials:

-X 'GET' \
  'https://{{example.com}}/api/history/v1?page=0&pageSize=999&entityIds%5B%5D={{UUID}}&entityIds%5B%5D={{UUID}}&organisationId={{UUID}}' \

By string

You can retrieve history entries containing a string. Use:

• searchText to set which string.
• searchType to set where to search.

If no searchType is set, the system searches all searchTypes:

• claimName searches claim keys.
• claimValue searches claim values.
• credentialSchemaName searches credential schema names.
• issuerDid searches issuer DID values.
• issuerName searches issuer DID names.
• verifierDid searches verifier DID values.
• verifierName searches verifier DID names.
• proofSchemaName searches proof schema names.

Here's an example curl query to retrieve all history events involving the claim key Birthdate:

-X 'GET' \
  'https://{{example.com}}/api/history/v1?page=0&pageSize=999&searchText=Birthdate&searchType=claimName&organisationId={{UUID}}' \

The response will include history entries for any credential or proof with a claim that contains "Birthdate" in a claim name. Note that "Birthdate" or any other searchText does not appear in the history entry itself.

By DID ID

You can retrieve history events associated with a DID. This includes not only the DID's own history events but also credential and proof events for that DID. Use:

• didId to set which DID.

Here's an example curl query to retrieve events for a DID, sorted by entitytype:

-X 'GET' \
  'https://{{example.com}}/api/history/v1?page=0&pageSize=999&sort=entityType&didId={{UUID}}&organisationId={{UUID}}' \

This will return history events for the DID's creation and potentially deactivation, and the issuance and verification interactions made using the DID.

Of OpenID providers

If you're using OpenID Bridge, you can filter its history events using sources[]=BRIDGE as described in By server component, then narrow further with:

• entityType=PROVIDER to get provider creation, deletion, and update events.
• entityType=INTERACTION to get login attempt events.
• providerId to return history events of a specific provider, including its interactions.

Here's an example curl query to retrieve provider history from OpenID Bridge:

-X 'GET' \
  'https://{{example.com}}/api/history/v1?page=0&pageSize=999&sources%5B%5D=BRIDGE&entityTypes%5B%5D=PROVIDER&organisationId={{UUID}}' \

By server component

If you have multiple services storing history in Core, you can filter events by their source. Use:

• sources[] to specify which service(s).

Available values:

• CORE — Core
• BFF — Enterprise Backend
• BRIDGE — OpenID Bridge
• STS — STS service
• WRPR — Wallet-Relying Party Registry

Here's an example curl query to retrieve history events from Core and Enterprise Backend:

-X 'GET' \
  'https://{{example.com}}/api/history/v1?page=0&pageSize=999&sources%5B%5D=CORE&sources%5B%5D=BFF&organisationId={{UUID}}' \

By user

You can retrieve history events triggered by specific users. Use:

• users[] to specify which user(s) by their user identifier (the sub claim from the STS token).

Here's an example curl query to retrieve history events for two users:

-X 'GET' \
  'https://{{example.com}}/api/history/v1?page=0&pageSize=999&users%5B%5D={{user_identifier}}&users%5B%5D={{user_identifier}}&organisationId={{UUID}}' \

Across organizations

By default, history queries are scoped to a single organization:

• In STS authentication mode, queries return events from the organization in your STS token.
• In other authentication modes, you must specify at least one organization in organisationIds[].

To query across multiple or all organizations, set showSystemHistory=true:

• In STS mode, this allows you to specify multiple organizations in organisationIds[], or omit it entirely to query all organizations. Requires the SYSTEM_HISTORY_LIST permission.
• In other authentication modes, this allows you to omit organisationIds[] to query all organizations.

You can combine showSystemHistory=true with other filters to narrow results while still searching across organizations.

Combining search methods

You can combine search methods.

Here's an example curl query to retrieve all claims deletion events for proof requests made using a particular proof schema, within a specified 24-hour period:

-X 'GET' \
  'https://{{example.com}}/api/history/v1?page=0&pageSize=999&entityId={{UUID}}&action=CLAIMS_REMOVED&createdDateAfter=2025-03-05T14%3A19%3A57.000Z&createdDateBefore=2025-03-06T14%3A19%3A57.000Z&didId={{UUID}}&organisationId={{UUID}}' \

In this case the entityId is used to specify the proof schema but, given the desired search parameters, the proofSchemaId could have been used as well.

How to export history

In the Enterprise Backend, use GET /api/history/v1/export to export a list of history events as CSV. This endpoint accepts the same filtering options as the list endpoint; results are sorted by createdDate.