History

Learn what the system records as history and how to read history logs.

History entries

The system records most events involving the following entities:

Credentials
Proofs
Keys
DIDs
Schemas
Organizations
Trust anchors
Trust entities
Backups (in the mobile SDK)
OpenID providers in Bridge

Each event is represented by a history entry containing:

The entity UUID and type
The action or event that took place
Metadata about the event

Here's a history entry of a credential revocation:

{
  "id": "b1de4a9b-3a3c-4528-8848-dd15565624b1",             // UUID of the event
  "createdDate": "2025-02-18T07:25:59.144Z",                // Date-time of the event
  "action": "REVOKED",                                      // What happened
  "entityId": "4f3efdf1-b286-436e-8ee5-e4c546a0bdca",       // UUID of the entity
  "entityType": "CREDENTIAL",                               // The type of entity
  "organisationId": "2476ebaa-0108-413d-aa72-c2a6babd423f"  // The organization the entity belongs to
},

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

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

SDK

By time frame

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

createdDateFrom to set a start time.
createdDateTo to set a stop time.

Here's an example curl query to retrieve all events since a date-time:

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

Since there is no createdDateTo, 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",
      "organisationId": "2476ebaa-0108-413d-aa72-c2a6babd423f"
    },
    {
      "id": "88e00dd1-ef16-4925-a00e-d1a82267e1aa",
      "createdDate": "2025-03-06T08:25:51.099Z",
      "action": "OFFERED",
      "entityId": "936bac3e-f9ed-4ce6-bae0-a1a6ba115d7a",
      "entityType": "CREDENTIAL",
      "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",
      "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",
      "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",
      "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",
      "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 a particular type of event. Use:

action to set which kind of event.

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

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

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

By entity type

You can retrieve history events of a particular entity type. Use:

entityType to set which kind of entity.

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

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

By entity ID

You can retrieve history entries of a particular entity. Use:

entityId to set which entity.

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

-X 'GET' \
  'https://{{example.com}}/api/history/v1?page=0&pageSize=999&entityId={{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 Bridge to integrate OpenID Connect providers, you can search history events of these integrations. In the Desk API use:

source: BRIDGE to get Bridge history events.

When using Bridge as the source of history events, you can narrow further using:

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

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

-X 'GET' \
  'https://desk.dev.procivis-one.com/api/history/v1?sortDirection=DESC&entityTypes=PROVIDER&source=BRIDGE' \

This will return history events for providers in Bridge.

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&createdDateFrom=2025-03-05T14%3A19%3A57.000Z&createdDateTo=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.

What's recorded

The following tables provide a reference for historical actions, organized by the type of entity.

Credentials

Action	Description
`ACCEPTED`	The credential transitioned to `ACCEPTED` state.
`CREATED`	The credential was created.
`DELETED`	The credential was deleted. This action has no impact on credential state.
`OFFERED`	The credential transitioned to `OFFERED` state.
`PENDING`	The credential transitioned to `PENDING` state.
`REJECTED`	The credential transitioned to `REJECTED` state.
`REVOKED`	The credential transitioned to `REVOKED` state.
`SHARED`	The credential transitioned to `SHARED` state.
`SUSPENDED`	The credential transitioned to `SUSPENDED` state.

Related guide: Credential states

Proofs

Action	Description
`ACCEPTED`	The proof transitioned to `ACCEPTED` state.
`CLAIMS_REMOVED`	The claim data was deleted from the proof.
`CREATED`	The proof request was created.
`ERRORED`	The proof transitioned to `ERROR` state.
`PENDING`	The proof transitioned to `PENDING` state.
`REJECTED`	The proof transitioned to `REJECTED` state.
`REQUESTED`	The proof transitioned to `REQUESTED` state.
`RETRACTED`	The proof transitioned to `RETRACTED` state.
`SHARED`	The proof transitioned to `SHARED` state.

Related guide: Proof request states

Keys

Action	Description
`CREATED`	The key was created.

DIDs

Action	Description
`CREATED`	The DID was created.
`DEACTIVATED`	The DID was deactivated.

Schemas

Action	Description
`CREATED`	The schema was created.
`DELETED`	The schema was deleted.
`SHARED`	The schema was shared with a mobile device.

Organizations

Action	Description
`CREATED`	The organization was created.

Trust anchors

Action	Description
`CREATED`	The trust anchor was created.
`DELETED`	The trust anchor was deleted.

Trust entities

Action	Description
`ACTIVATED`	A removed or withdrawn entity was reactivated to a trust anchor.
`CREATED`	The trust entity was published to a trust anchor.
`REMOVED`	The trust entity was removed from a trust anchor by the anchor publisher.
`WITHDRAWN`	The trust entity was withdrawn from a trust anchor by the entity.

Backups

Action	Description
`CREATED`	A backup was created.
`RESTORED`	The import was finalized and the database was overwritten with the content of the backup.

OpenID providers in Bridge

Action	Description
`CLIENT_SECRET_REGENERATED`	The provider client secret was regenerated.
`CREATED`	The provider was created.
`DELETED`	The provider was deleted.
`ERRORED`	The login attempt resulted in an error.
`SUCCEEDED`	The login attempt was successful.
`UPDATED`	The provider was updated (attributes not including client secret).

History entries​

How to search history​

By time frame​

By schema ID​

By action​

By entity type​

By entity ID​

By string​

By DID ID​

Of OpenID providers​

Combining search methods​

What's recorded​

Credentials​

Proofs​

Keys​

DIDs​

Schemas​

Organizations​

Trust anchors​

Trust entities​

Backups​

OpenID providers in Bridge​