Indicio Proven API Documentation

General Information

HTTP Headers

All “v1” APIs require an “x-api-key” header to be set on the request. The “x-api-key” is not just used for authorization; it’s also used to determine which wallet will complete the request.

Wallet ID

Proven supports a multi-tenant environment by default, even if you only intend to use a single wallet for this installed agent. Each wallet is identified by a wallet ID. Because these wallet IDs are linked to the API key(s) you will create, you don’t have to pay close attention to the wallet ID when using the API.

Multi-Tenancy

Proven can support multiple instances and various configurations of decentralized identity software on a single machine. Each software installation is referred to as an agent, and each logical subdivision of the software is referred to as a wallet; in other words, one installation can be configured to act as several independent copies of decentralized identity software. This concept of having multiple software units running independently on the same machine is called multi-tenancy.

Proven manages multi-tenancy by associating each wallet with a user group and allowing the administrator to assign users to groups (and thereby wallets). Thus, each installation can have multiple wallets, multiple users per wallet, and multiple wallets per user.

Wallet authentication in Proven is handled via OpenID Connect, and the user's group is determined by the IAM service (Keycloak is the default for Proven). The IAM service provides the user's group and permissions, which Proven uses to determine the appropriate wallet for the user's operations.

Managing Wallets

Login

To log in, navigate to http://your-domain-name.com/auth/login. You will be redirected from Proven to a Keycloak login page, where you will log in with the user “indicio” and password “adminadminadmin”. After successful authentication, you will be redirected back to Proven. Keycloak will pass an OpenID Connect token, which will log the user in automatically. You will then see the Proven dashboard with the user “indicio” logged in.

Create Wallets and API Keys

To manage wallets and their API keys, navigate to the Proven “Multi-tenancy” page. Click “Create Subwallet” to generate a new wallet.

To create an API key, select the wallet to which the new API key will belong from the drop-down menu and check the roles that the API key will have. After creation, store the API key and its ID securely (this is the only time that the API key will be available). To revoke an API key, use the API key ID and Wallet ID to indicate which API key will be revoked.

Managing Users

Proven-UI does not have any pages for managing users. To manage users, you must use the Keycloak admin console. The linking of users to wallets requires the group ID entered into Keycloak.

Adding Users to a Wallet

To add users to a new wallet, follow these steps:

1. Create a New Group in Keycloak:

   1. Select the “Indicio Proven Realm”

   2. Click on “Groups” in the left menu

   3. Click on the “Create group” button and name the group. The group name must match the wallet name that was created

   4. Click on the new group in the list of groups

   5. Click on the “Attributes” tab

   6. Click on “Add attributes”

   7. Enter "proven_group_id" as the key and the wallet name as the Value

   8. Click the “Save” button

2. Add New Users to the Group:

   1. Select the “Indicio Proven Realm”

   2. Click on “Users” in the left menu

   3. Select the user to add to the wallet

   4. Click on the “Groups” tab

   5. Click on the “Join Group” button

   6. Select the group(s) (which correspond to wallets) that you would like to add the user to

   7. Click the “Join” button

3. Log in to Proven:

   1. The first user to log in to the new wallet must have the “super-admin” role to complete the linking of the user group to the wallet.

   2. The super-admin user must simply log in to Proven to complete this operation.

By following these steps, the new user group and its associated users will be created and associated with the specified wallet.

Using API Key Endpoints

In addition to an administrative UI, Proven offers an API for the programmatic execution of agent operations. Its OpenAPI specification can be found at http://your-domain-name.com/api/doc of the server you are working with.

Proven uses API keys to authenticate requests to the API and authorize the API user's access to the requested resource. Proven uses the API key to determine the user's group and permissions, which are used to determine the appropriate wallet for the user's operations.

Environment Variables

To use API keys, you must set the following environment variable:

Variable	Explanation
PROVEN_APIKEY	The base API key needed for management of wallets and API keys

API Key Creation Using the Swagger UI:

To create a new API key, you will need the base wallet API key. The base wallet API key is used to create wallets and their associated API keys. It can be found in the .env file as PROVEN_APIKEY.

Once you have the base wallet API key, you will need to be authorized before you can create new API keys.

1. Click the “Authorize” button at the top right of the page.

2. Enter the API key in the “Value” field.

3. Click the “Authorize” button.

Wallet API keys are used to authenticate requests to the Proven API. To create a new API key using Swagger, navigate to http://your-domain-name.com/api/doc.

1. Create a new wallet if it is not already created.

2. Navigate to the API Keys tab and click the “Create API Key” button.

3. Enter the wallet_id for the wallet to which the API key will belong.

4. Click the “Create” button.

5. The API key will be displayed in the table. Copy the API key and store it securely.

API keys are not stored by Proven; after the first creation of the key, there is no way to retrieve it. If the API key is lost, a new one must be created. Proven API requests must include the key in the request headers.

API keys have associated roles, which determine multitenancy privileges in the following manner:

• super-admin: Can create and revoke API keys for any wallet with any set of roles

• admin: Can create and revoke API keys in their wallet for any set of roles that are the same or a subset of its own

• technician and other limited roles: Have no multitenancy privileges

The base API key is used to allow the base admin user to create and manage wallets and their API keys. The base admin user cannot perform most wallet API operations; to use most of the API, a wallet and its API key are needed.

API Key Flow Explanation:

1. User Requests API Key: The user requests to generate an API key.

2. Generate Random String: The API generates an opaque random string using a secure random source.

3. Present API Key: The API presents the random string (API key) to the user.

4. Store API Key Securely: The user stores the API key securely.

5. HMAC the String: The API HMACs the string with a secret.

6. Store HMACed Value: The API stores the HMACed value in the database.

7. Send API Request: The user sends an API request with the API key in the headers.

8. HMAC the Received Key: The API HMACs the received API key with the same secret.

9. Check User Role: The API checks the user's role.

10. Look Up HMACed Value: The API looks up the HMACed value in the database.

11. Return Metadata: The database returns metadata if the key is valid and not revoked.

12. Process Request: The API processes the request and returns the response to the user if the role is valid.

13. Return Error: The API returns an error if the role is invalid.

Distinction Between HTTP Endpoints:

• Internal: Accessible using the Base API Key

  • Wallet creation

  • API Key creation and revocation

• External: Accessible through the use of wallet API Keys (which are created by the Base API Key for a particular wallet) or by a User in the Proven UI (which accesses information via the Proven WS API)

  • All other API endpoints

API Contents

Proven DIDComm APIs

Basic Messages

Basic Message - Create Basic Message

/api/v1/messages - POST

This endpoint creates a Basic Message record that handles sending messages to currently active connection(s) or future active connection(s) until the request record reaches a completed state.

Request Body Information:

Field name	Expected type/values	Examples	Notes
invitation_id	integer	123	Optional integer used to process the request record by a connection tied to the invitation_id. Used with contact_id, has second priority
contact_id	string	contact123	Optional contact ID string used for processing the request record by known contact. Used with invitation_id, has first priority
message	string	Hello world!	Message content

Response Body Information:

Field name	Expected type/values	Examples	Notes
success	string	Message was sent!	Success message

Sample Response Body:

{ "success": "Message was sent!" }

Basic Message - Read All Basic Messages

/api/v1/messages - GET

This endpoint fetches all Basic Message records.

Request Body Information:

No request body

Response Body Information:

The response body is an array of records. The following information is the data of each record:

Field name	Expected type/values	Examples	Notes
id	integer	123	Primary identifier for record
message_id	string	2ff097c3-5b65-4c25-a836-e2e3edb8195e	Unique identifier for exchange message
contact_id	string	199e022b-bb4c-4ae4-99fe-395b50ad4b66	Optional contact ID string used for processing the request record by known contact. Used with invitation_id, has first priority
invitation_id	integer	123	Optional integer used to process the request record by a connection tied to the invitation_id. Used with contact_id, has second priority
message	string	Hello World!	Message content
state	string	sent	Current state of Basic Message request record
sent_time	string	2024-12-30T13:17:40.107Z	Date/time the message was sent to connection (ACA-Py field)
locale	string	null	Not used at present
wallet_id	string	199e022b-bb4c-4ae4-99fe-395b50ad4b66	Identifier of the wallet used to process the request. The wallet used is determined by the x-api-key.
created_at	string	2024-12-30T13:17:40.108Z	Date of creation for the Basic Message record
updated_at	string	2024-12-30T13:17:40.108Z	Date the Basic Message record was last updated

Sample Response Body:

[
   {
       "id": 1,
       "message_id": "",
       "contact_id": "199e022b-bb4c-4ae4-99fe-395b50ad4b66",
       "invitation_id": 1,
       "message": "Multiple Contact Hello World!",
       "state": "sent",
       "sent_time": "2024-12-30T13:17:40.107Z",
       "locale": "",
       "wallet_id": "eea19d5b-cbfc-44a0-9406-a9bddcbe3994",
       "created_at": "2024-12-30T13:17:40.108Z",
       "updated_at": "2024-12-30T13:17:40.648Z"
   }
]

Basic Message - Read Basic Message by ID

/api/v1/messages/<id> - GET

This endpoint fetches a Basic Message record by its ID.

Request Body Information:

No request body

Response Body Information:

Field name	Expected type/values	Examples	Notes
id	integer	123	Primary identifier for record
message_id	string	2ff097c3-5b65-4c25-a836-e2e3edb8195e	Unique identifier for exchange message
contact_id	string	199e022b-bb4c-4ae4-99fe-395b50ad4b66	Optional contact ID string used for processing the request record by known contact. Used with invitation_id, has first priority
invitation_id	integer	123	Optional integer used to process the request record by a connection tied to the invitation_id. Used with contact_id, has second priority
message	string	Hello World!	Message content
state	string	sent	Current state of Basic Message request record
sent_time	string	2024-12-30T13:17:40.107Z	Date/time the message was sent to connection (ACA-Py field)
locale	string	null	Not used at present
wallet_id	string	199e022b-bb4c-4ae4-99fe-395b50ad4b66	Identifier of the wallet used to process the request. The wallet used is determined by the x-api-key.
created_at	string	2024-12-30T13:17:40.108Z	Date of creation for the Basic Message record
updated_at	string	2024-12-30T13:17:40.108Z	Date the Basic Message record was last updated

Sample Response Body:

  {
      "id": 1,
      "message_id": "",
      "contact_id": "199e022b-bb4c-4ae4-99fe-395b50ad4b66",
      "invitation_id": 1,
      "message": "Multiple Contact Hello World!",
      "state": "sent",
      "sent_time": "2024-12-30T13:17:40.107Z",
      "locale": "",
      "wallet_id": "eea19d5b-cbfc-44a0-9406-a9bddcbe3994",
      "created_at": "2024-12-30T13:17:40.108Z",
      "updated_at": "2024-12-30T13:17:40.648Z"
    }

Connections

Connections - Read All Connections

/api/v1/connections - GET

This endpoint fetches all connections, and includes parameters for pagination purposes.

Request URL Parameters Information:

Field name	Expected type/values	Examples	Notes
sort-field	text	contact_id	Optional, any of the field names listed in the "Create invitation" POST body plus invitation_id
sort-direction	text	ASC	Optional, ASC or DESC
page-size	int	10	Optional, how many items should be returned in a page
current-page	int	2	Optional, the current page to retrieve
item-count	int	10	Optional, the total number of items

Sample URLs:

https://your-domain-name.com/api/v1/connections?sort-field=contact_id&sort-direction=ASC&page-size=10&current-page=2

Request Body Information:

No request body

Response Body Information:

The response body has three sections:

• Params: The pagination and sorting parameters

  • "sort": “DESC”

  • "pageSize": "10"

  • "currentPage": 1

  • "pageCount": 1

  • "itemCount": 1

• Rows: The array of records

  • Each row in the rows array has the properties found in the table below.

• Count: The number of items returned

  • “count”: 3

Field name	Expected type/values	Examples	Notes
connection_id	string	d61b698f-2eb4-438d-bec0-a7f88bcb47f0	Unique and primary identifier for the connection
state	string	active	Invitation, init, request, response, active, error, deleted
my_did	string	TP1jLwshBSSUArz154iLg2	Decentralized identifier
alias	string	Proven	String for how this connection could be labeled in the receiving agent
request_id	string	5f2b5d38-b3ad-43af-9b50-98df250e600e	ACA-Py field
invitation_key	string	7FQqpV7jepn5pf5jmkYwuXgQXrN9QeDSUw2tE8vaWAf7	ACA-Py field tied to the invitation used to establish the connection
invitation_msg_id	string	afbc12b7-28fa-4936-bf11-748148a98ffc	ACA-Py field tied to the invitation
invitation_mode	string	once	once, multi
invitation_url	string	https://<domain>?oob=<base64 invitation>	Invitation_url used to establish the connection
invitation	object	{...}	Raw invitation data used by the receiving agent to connect
accept	string	auto	ACA-Py field/parameter
initiator	string	null	ACA-Py field
their_role	string	inviter	inviter, invitee
their_did	string	PhTeNogZWHmjCqiyPr8cds	Connecting wallet’s DID (sender or receiver, depending on who generated the invitation)
their_public_did	string	null	Connecting wallet’s Public DID (sender or receiver, depending on who generated the invitation)
their_label	string	Holdr+	Label used by this wallet to identify this connection
routing_state	string	null	ACA-Py field
inbound_connection_id	string	null	ACA-Py field
error_msg	string	null	Error message provided by ACA-Py during exchange
contact_id	string	0846c509-4a6e-4022-bebd-e2e9ff63b747	Identifier of the Contact tied to this connection
discover_features	array	[...]	List of available features for this connection
wallet_id	string	eea19d5b-cbfc-44a0-9406-a9bddcbe3994	Unique identifier of the wallet tied to this connection
created_at	timestamp	2024-12-30T10:37:30.734Z	Date/time of creation for the connection record
updated_at	timestamp	2024-12-30T10:37:31.686Z	Date/time the connection record was last updated

Sample Response Body:

{
  "params": {
      "sort": [
          [
              [
                  "updated_at",
                  "DESC"
              ]
          ]
      ],
      "pageSize": "2",
      "currentPage": 2,
      "pageCount": 2,
      "itemCount": 3
  },
  "rows": [
      {
          "connection_id": "65eb5586-e519-441d-a05c-c3c697ecd97a",
          "state": "active",
          "my_did": "TP1jLwshBSSUArz154iLg2",
          "alias": "Proven",
          "request_id": "5f2b5d38-b3ad-43af-9b50-98df250e600e",
          "invitation_key": "7FQqpV7jepn5pf5jmkYwuXgQXrN9QeDSUw2tE8vaWAf7",
          "invitation_msg_id": "afbc12b7-28fa-4936-bf11-748148a98ffc",
          "invitation_mode": "once",
          "invitation_url": "https://hard-tiger-38.tun2.indiciotech.io?oob=eyJAdHlwZSI6ICJodHRwczovL2RpZGNvbW0ub3JnL291dC1vZi1iYW5kLzEuMS9pbnZpdGF0aW9uIiwgIkBpZCI6ICJhZmJjMTJiNy0yOGZhLTQ5MzYtYmYxMS03NDgxNDhhOThmZmMiLCAibGFiZWwiOiAiUHJpbWFyeVdhbGxldCIsICJoYW5kc2hha2VfcHJvdG9jb2xzIjogWyJodHRwczovL2RpZGNvbW0ub3JnL2RpZGV4Y2hhbmdlLzEuMCJdLCAic2VydmljZXMiOiBbeyJpZCI6ICIjaW5saW5lIiwgInR5cGUiOiAiZGlkLWNvbW11bmljYXRpb24iLCAicmVjaXBpZW50S2V5cyI6IFsiZGlkOmtleTp6Nk1ra2hmdFFqTkF6TkdZdzl2U1RLV25rZEVRTVJkenBYVG9Bd3dwNFF0YlJQU1YjejZNa2toZnRRak5Bek5HWXc5dlNUS1dua2RFUU1SZHpwWFRvQXd3cDRRdGJSUFNWIl0sICJzZXJ2aWNlRW5kcG9pbnQiOiAiaHR0cHM6Ly9oYXJkLXRpZ2VyLTM4LnR1bjIuaW5kaWNpb3RlY2guaW8ifV19",
          "invitation": {
              "@type": "https://didcomm.org/out-of-band/1.1/invitation",
              "@id": "afbc12b7-28fa-4936-bf11-748148a98ffc",
              "label": "PrimaryWallet",
              "handshake_protocols": [
                  "https://didcomm.org/didexchange/1.0"
              ],
              "services": [
                  {
                      "id": "#inline",
                      "type": "did-communication",
                      "recipientKeys": [
                          "did:key:z6MkkhftQjNAzNGYw9vSTKWnkdEQMRdzpXToAwwp4QtbRPSV#z6MkkhftQjNAzNGYw9vSTKWnkdEQMRdzpXToAwwp4QtbRPSV"
                      ],
                      "serviceEndpoint": "https://hard-tiger-38.tun2.indiciotech.io"
                  }
              ]
          },
          "accept": "auto",
          "initiator": null,
          "their_role": "inviter",
          "their_did": "PhTeNogZWHmjCqiyPr8cds",
          "their_public_did": null,
          "their_label": "PrimaryWallet",
          "routing_state": null,
          "inbound_connection_id": null,
          "error_msg": null,
          "contact_id": "0846c509-4a6e-4022-bebd-e2e9ff63b747",
          "transaction_role": null,
          "discovered_features": [...],
          "wallet_id": "eea19d5b-cbfc-44a0-9406-a9bddcbe3994",
          "created_at": "2024-12-30T10:37:30.734Z",
          "updated_at": "2024-12-30T10:37:31.686Z"
      }
  ],
  "count": 3
}

Connections - Read Connection by ID

/api/v1/connections/<connection_id> - GET

This endpoint fetches a connection record by its connection_id.

Request Body Information:

No request body

Response Body Information:

Field name	Expected type/values	Examples	Notes
connection_id	string	d61b698f-2eb4-438d-bec0-a7f88bcb47f0	Unique and primary identifier for the connection
state	string	active	Invitation, init, request, response, active, error, deleted
my_did	string	TP1jLwshBSSUArz154iLg2	Decentralized identifier
alias	string	Proven	String for how this connection could be labeled in the receiving agent
request_id	string	5f2b5d38-b3ad-43af-9b50-98df250e600e	ACA-Py field
invitation_key	string	7FQqpV7jepn5pf5jmkYwuXgQXrN9QeDSUw2tE8vaWAf7	ACA-Py field tied to the invitation used to establish the connection
invitation_msg_id	string	afbc12b7-28fa-4936-bf11-748148a98ffc	ACA-Py field tied to the invitation
invitation_mode	string	once	once, multi
invitation_url	string	https://<domain>?oob=<base64 invitation>	Invitation_url used to establish the connection
invitation	object	{...}	Raw invitation data used by the receiving agent to connect
accept	string	auto	ACA-Py field/parameter
initiator	string	null	ACA-Py field
their_role	string	inviter	inviter, invitee
their_did	string	PhTeNogZWHmjCqiyPr8cds	Connecting wallet’s DID (sender or receiver, depending on who generated the invitation)
their_public_did	string	null	Connecting wallet’s Public DID (sender or receiver, depending on who generated the invitation)
their_label	string	Holdr+	Label used by this wallet to identify this connection
routing_state	string	null	ACA-Py field
inbound_connection_id	string	null	ACA-Py field
error_msg	string	null	Error message provided by ACA-Py during exchange
contact_id	string	0846c509-4a6e-4022-bebd-e2e9ff63b747	Identifier of the Contact this connection is tied to
discover_features	array	[...]	List of available features for this connection
wallet_id	string	eea19d5b-cbfc-44a0-9406-a9bddcbe3994	Unique identifier of the wallet this connection is tied to
created_at	timestamp	2024-12-30T10:37:30.734Z	Date/time of creation for the connection record
updated_at	timestamp	2024-12-30T10:37:31.686Z	Date/time the connection record was last updated

Sample Response Body:

{
      "connection_id": "65eb5586-e519-441d-a05c-c3c697ecd97a",
      "state": "active",
      "my_did": "TP1jLwshBSSUArz154iLg2",
      "alias": "Proven",
      "request_id": "5f2b5d38-b3ad-43af-9b50-98df250e600e",
      "invitation_key": "7FQqpV7jepn5pf5jmkYwuXgQXrN9QeDSUw2tE8vaWAf7",
      "invitation_msg_id": "afbc12b7-28fa-4936-bf11-748148a98ffc",
      "invitation_mode": "once",
      "invitation_url": "https://hard-tiger-38.tun2.indiciotech.io?oob=eyJAdHlwZSI6ICJodHRwczovL2RpZGNvbW0ub3JnL291dC1vZi1iYW5kLzEuMS9pbnZpdGF0aW9uIiwgIkBpZCI6ICJhZmJjMTJiNy0yOGZhLTQ5MzYtYmYxMS03NDgxNDhhOThmZmMiLCAibGFiZWwiOiAiUHJpbWFyeVdhbGxldCIsICJoYW5kc2hha2VfcHJvdG9jb2xzIjogWyJodHRwczovL2RpZGNvbW0ub3JnL2RpZGV4Y2hhbmdlLzEuMCJdLCAic2VydmljZXMiOiBbeyJpZCI6ICIjaW5saW5lIiwgInR5cGUiOiAiZGlkLWNvbW11bmljYXRpb24iLCAicmVjaXBpZW50S2V5cyI6IFsiZGlkOmtleTp6Nk1ra2hmdFFqTkF6TkdZdzl2U1RLV25rZEVRTVJkenBYVG9Bd3dwNFF0YlJQU1YjejZNa2toZnRRak5Bek5HWXc5dlNUS1dua2RFUU1SZHpwWFRvQXd3cDRRdGJSUFNWIl0sICJzZXJ2aWNlRW5kcG9pbnQiOiAiaHR0cHM6Ly9oYXJkLXRpZ2VyLTM4LnR1bjIuaW5kaWNpb3RlY2guaW8ifV19",
      "invitation": {
          "@type": "https://didcomm.org/out-of-band/1.1/invitation",
          "@id": "afbc12b7-28fa-4936-bf11-748148a98ffc",
          "label": "PrimaryWallet",
          "handshake_protocols": [
              "https://didcomm.org/didexchange/1.0"
          ],
          "services": [
              {
                  "id": "#inline",
                  "type": "did-communication",
                  "recipientKeys": [ "did:key:z6MkkhftQjNAzNGYw9vSTKWnkdEQMRdzpXToAwwp4QtbRPSV#z6MkkhftQjNAzNGYw9vSTKWnkdEQMRdzpXToAwwp4QtbRPSV"
                  ],
                  "serviceEndpoint": "https://hard-tiger-38.tun2.indiciotech.io"
              }
          ]
      },
      "accept": "auto",
      "initiator": null,
      "their_role": "inviter",
      "their_did": "PhTeNogZWHmjCqiyPr8cds",
      "their_public_did": null,
      "their_label": "PrimaryWallet",
      "routing_state": null,
      "inbound_connection_id": null,
      "error_msg": null,
      "contact_id": "0846c509-4a6e-4022-bebd-e2e9ff63b747",
      "transaction_role": null,
      "discovered_features": [...],
      "wallet_id": "eea19d5b-cbfc-44a0-9406-a9bddcbe3994",
      "created_at": "2024-12-30T10:37:30.734Z",
      "updated_at": "2024-12-30T10:37:31.686Z"
  }

Context

Context - Save JSON-LD Context File

/api/v1/context - POST

This endpoint saves a JSON-LD context file.

Request Body Information:

Field name	Expected type/values	Examples	Notes
context_file_id	string	test.json	File name of the JSON-LD context file to save
file	object	{...}	Object containing JSON-LD contexts

Request Body Sample:

 {
  "context_file_id": "test.json",
  "file": {
    "@context": {
      "GenericCredential": {
        "@id": "https://example.com/indicio#GenericCredential",
        "@context": {
          "name": "http://schema.org/name",
          "givenName": "http://schema.org/givenName",
          "familyName": "http://schema.org/familyName",
          "identifier": "https://example.com/indicio#identifier",
          "date": {
            "@id": "http://schema.org/date",
            "@type": "http://www.w3.org/2001/XMLSchema#date"
          },
          "description": "http://schema.org/description"
        }
      }
    }
  }
}

Response Body Information:

Field name	Expected type/values	Examples	Notes
success	string	Context file was posted	Success message

Sample Response Body:

{ "success": "Context file was posted" }

Credentials

Credentials - Create Credential Issuance (JSON-LD)

/api/v1/credentials/json-ld - POST

This endpoint creates an Issuance request record that handles issuing credentials (JSON-LD) for currently active connection(s) or future active connection(s) until the request record reaches a completed state.

Request Body Information:

Field name	Expected type/values	Examples	Notes
invitation_id	integer	123	Optional integer used to process the request record by a connection tied to the invitation_id. Used with contact_id, has second priority
contact_id	text	contact123	Optional contact ID string used for processing the request record by known contact. Used with invitation_id, has first priority
context	array	https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json	Contexts of the credential
label	string	Drivers License	Credentials label
issuer_name	string	Proven	Name of the issuer
type	array	[...]	Types of the credential
attributes	array	[{“name”: “first_name”, “value”: “Alice”}]	The “name” accepts string data type only. The “value” accepts string, object, and array data types
timeout	integer	10	Number of seconds the initial request will wait for a completed record
rule	string	no rule	Rules enforced for this request (future feature)
did	string	did:indy:indicio:demo:JcBoFbZQo9yd3SWUc6Lvbt	Decentralized identifier used to sign the credential
proofType	string	Ed25519Signature2020	Type of proof to generate to sign the credential. Defaults to Ed25519Signature2018

Response Body Information:

Field name	Expected type/values	Examples	Notes
request_id	integer	1	Records primary key
connection_id	string	f7699aa9-beec-4e0c-868d-eb3766ad2f64	Connection used for this request, determined by invitation_id and contact_id
contact_id	text	contact123	Optional contact ID string used for processing the request record by known contact. Used with invitation_id, has first priority
invitation_id	integer	123	Optional integer used to process the request record by a connection tied to the invitation_id. Used with contact_id, has second priority
context	array	https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json	Contexts of the credential
label	string	Drivers License	Credentials label
type	array	[...]	Types of the credential
attributes	array	[{“name”: “first_name”, “value”: “Alice”}]	The “name” accepts string data type only. The “value” accepts string, object, and array data types
wallet_id	string	eea19d5b-cbfc-44a0-9406-a9bddcbe3994	Identifier that ties this record to an existing wallet
issuer_name	string	Proven	Name of the issuer
timeout	integer	10	Number of seconds the initial request will wait for a completed record
rule	string	“no rule”	Rules enforced for this request (future feature)
meta_data	object	{...}	Metadata for this credential
state	string	offer_sent	ACA-Py field - null means no issuance has been triggered yet, likely due to no available connection
complete	boolean	false	This field does not indicate successful issuance, only that the request record has finished its process.
result	boolean	false	Indicates successful issuance result. This field should be used alongside “complete” to determine successful request record.
result_string	string	“Pending”	Custom string for helping to define the state of the request
credential_exchange_id	array	[...]	Contains unique IDs for each issued credential
error	string	“Public DID not set.”	Error message caught while processing request record
issuer_did	string	did:indy:indicio:demo:JcBoFbZQo9yd3SWUc6Lvbt	Issuer’s decentralized identifier
proof_type	string	Ed25519Signature2020	Type of proof to generate to sign the credential - defaults to Ed25519Signature2018.
created_at	timestamp	2024-12-31T09:34:31.635Z	Date/time this record was created
updated_at	timestamp	2024-12-31T09:34:31.635Z	Date/time this record was last updated

Sample Response Body:

[
  {
      "request_id": 1,
      "connection_id": "f7699aa9-beec-4e0c-868d-eb3766ad2f64",
      "contact_id": "",
      "invitation_id": 1,
      "context": [
          "https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json"
      ],
      "label": "マルチテナント検証_003",
      "type": [
          "OpenBadgeCredential"
      ],
      "attributes": [...],
      "wallet_id": "eea19d5b-cbfc-44a0-9406-a9bddcbe3994",
      "issuer_name": "PrimaryWallet",
      "timeout": 0,
      "rule": "no rule",
      "meta_data": null,
      "state": null,
      "complete": false,
      "result": false,
      "result_string": "Pending",
      "credential_exchange_id": [
          "fca9d9cb-d93c-4383-bcb3-71454aa5d62c"
      ],
      "error": "",
      "issuer_did": "did:sov:JHQQDXd1MophrGnygoj3L4",
      "proof_type": "Ed25519Signature2018",
      "created_at": "2024-12-31T09:34:31.635Z",
      "updated_at": "2024-12-31T09:34:33.095Z"
  }
]

Credentials - Read Credential Issuance by ID (JSON-LD)

/api/v1/credentials/json-ld/<request_id> - GET

This endpoint fetches a credential (JSON-LD) Issuance request record by its request_id.

Request Body Information:

No request body

Response Body Information:

Field name	Expected type/values	Examples	Notes
request_id	integer	1	Records primary key
connection_id	string	f7699aa9-beec-4e0c-868d-eb3766ad2f64	Connection used for this request, determined by invitation_id and contact_id
contact_id	text	contact123	Optional contact ID string used for processing the request record by known contact. Used with invitation_id, has first priority
invitation_id	integer	123	Optional integer used to process the request record by a connection tied to the invitation_id. Used with contact_id, has second priority
context	array	https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json	Contexts of the credential
label	string	Drivers License	Credentials label
type	array	[...]	Types of the credential
attributes	array	[{“name”: “first_name”, “value”: “Alice”}]	The “name” accepts string data type only. The “value” accepts string, object, and array data types.
wallet_id	string	eea19d5b-cbfc-44a0-9406-a9bddcbe3994	Identifier that ties this record to an existing wallet
issuer_name	string	Proven	Name of the issuer
timeout	integer	10	Number of seconds the initial request will wait for a completed record
rule	string	“no rule”	Rules enforced for this request (future feature)
meta_data	object	{...}	Metadata for this credential
state	string	offer_sent	Null means no issuance has been triggered yet, likely due to no available connection
complete	boolean	false	This field does not indicate successful issuance, only that the request record has finished its process.
result	boolean	false	Indicates successful issuance result. This field should be used alongside “complete” to determine successful request record.
result_string	string	“Pending”	Custom string for helping to define the state of the request
credential_exchange_id	array	[...]	Contains unique IDs for each issued credential.
error	string	“Public DID not set.”	Error message caught while processing request record
issuer_did	string	did:indy:indicio:demo:JcBoFbZQo9yd3SWUc6Lvbt	Issuer’s decentralized identifier
proof_type	string	Ed25519Signature2020	Type of proof to generate to sign the credential. Defaults to Ed25519Signature2018
created_at	timestamp	2024-12-31T09:34:31.635Z	Date/time this record was created
updated_at	timestamp	2024-12-31T09:34:31.635Z	Date/time this record was last updated

Sample Response Body:

[
  {
      "request_id": 1,
      "connection_id": "f7699aa9-beec-4e0c-868d-eb3766ad2f64",
      "contact_id": "",
      "invitation_id": 1,
      "context": [
          "https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json"
      ],
      "label": "マルチテナント検証_003",
      "type": [
          "OpenBadgeCredential"
      ],
      "attributes": [...],
      "wallet_id": "eea19d5b-cbfc-44a0-9406-a9bddcbe3994",
      "issuer_name": "PrimaryWallet",
      "timeout": 0,
      "rule": "no rule",
      "meta_data": null,
      "state": null,
      "complete": false,
      "result": false,
      "result_string": "Pending",
      "credential_exchange_id": [
          "fca9d9cb-d93c-4383-bcb3-71454aa5d62c"
      ],
      "error": "",
      "issuer_did": "did:sov:JHQQDXd1MophrGnygoj3L4",
      "proof_type": "Ed25519Signature2018",
      "created_at": "2024-12-31T09:34:31.635Z",
      "updated_at": "2024-12-31T09:34:33.095Z"
  }
]

Credentials - Create Credential Issuance (AnonCred)

/api/v1/credentials - POST

This endpoint creates an Issuance request record that handles issuing credentials (AnonCred) for currently active connection(s) or future active connection(s) until the request record reaches a completed state.

Request Body Information:

Field name	Expected type/values	Examples	Notes
invitation_id	integer	123	Optional integer used to process the request record by a connection tied to the invitation_id. Used with contact_id, has second priority
contact_id	text	contact123	Optional contact ID string used for processing the request record by known contact. Used with invitation_id, has first priority
schema_id	text	KT4LtL7HEMePqQSyKVof7g:2:Email:1.0	Credentials schema
attributes	array	[{“name”: “first_name”, “value”: “Alice”}]	List of schema attribute names and their values
timeout	integer	10	Number of seconds the initial request will wait for a completed record
rule	string	no rule	Rules enforced for this request (future feature)

Response Body Information:

The response body is an array of records. The following information is the data of each record:

Field name	Expected type/values	Examples	Notes
request_id	integer	123	Issuance request record primary key
connection_id	string	cdcff763-5616-4a43-90ee-b0a38e0f6646	Ties record to the connection used to complete the request
contact_id	text	contact123	Optional contact ID string used for processing the request record by known contact. Used with invitation_id, has first priority
invitation_id	integer	123	Optional integer used to process the request record by a connection tied to the invitation_id. Used with contact_id, has second priority
schema_id	text	KT4LtL7HEMePqQSyKVof7g:2:Email:1.0	Credentials schema
attributes	array	[{“name”: “first_name”, “value”: “Alice”}]	List of schema attribute names and their values
wallet_id	string	199e022b-bb4c-4ae4-99fe-395b50ad4b66	Identifier that ties this record to an existing wallet
timeout	integer	10	Number of seconds the initial request will wait for a completed record
rule	string	no rule	Rules enforced for this request (future feature)
meta_data	object	null	Metadata for this credential
state	string	offer_sent	Null means no issuance has been triggered yet, likely due to no available connection.
complete	boolean	false	This field does not indicate successful issuance, only that the request record has finished its process.
result	boolean	false	Indicates successful issuance result. This field should be used alongside “complete” to determine if you have a successful request record.
result_string	string	“Pending”	Custom string for helping to define the state of the request
credential_exchange_id	array	[...]	Contains unique IDs for each issued credential.
error	string	“Public DID not set.”	Error message caught while processing request record
created_at	timestamp	2024-12-31T09:34:31.635Z	Date/time this record was created
updated_at	timestamp	2024-12-31T09:34:31.635Z	Date/time this record was last updated

Sample Response Body:

[
  {
    "request_id": 1,
    "connection_id": "cdcff763-5616-4a43-90ee-b0a38e0f6646",
    "contact_id": "",
    "invitation_id": 1,
    "schema_id": "KT4LtL7HEMePqQSyKVof7g:2:Email:1.0",
    "attributes": [
      {
        "name": "local_part",
        "value": "alice"
      },
      {
        "name": "domain",
        "value": "example.com"
      },
      {
        "name": "address",
        "value": "[email protected]"
      },
      {
        "name": "verified_at",
        "value": "1670296277"
      }
    ],
    "wallet_id": "f20823bb-9079-4026-b9dc-a7f410af5141",
    "timeout": 1,
    "rule": "no rule",
    "meta_data": null,
    "state": null,
    "complete": false,
    "result": false,
    "result_string": "Pending",
    "credential_exchange_id": [
      "5d00c38f-cc6a-4f0c-9dd2-3813c0dd8134"
    ],
    "error": "",
    "created_at": "2025-01-03T12:57:35.090Z",
    "updated_at": "2025-01-03T12:57:37.842Z"
  }
]

Credentials - Read Credential Issuance by ID (AnonCred)

/api/v1/credential-records/<request_id> - GET

This endpoint fetches a credential Issuance record by its request_id.

Request Body Information:

No request body

Response Body Information:

Field name	Expected type/values	Examples	Notes
request_id	integer	123	Issuance request record primary key
connection_id	string	cdcff763-5616-4a43-90ee-b0a38e0f6646	Identifier that ties this record to a connection
contact_id	text	contact123	Optional contact ID string used for processing the request record by known contact. Used with invitation_id, has first priority
invitation_id	integer	123	Optional integer used to process the request record by a connection tied to the invitation_id. Used with contact_id, has second priority
schema_id	text	KT4LtL7HEMePqQSyKVof7g:2:Email:1.0	Credentials schema
attributes	array	[{“name”: “first_name”, “value”: “Alice”}]	List of schema attribute names and their values
wallet_id	string	199e022b-bb4c-4ae4-99fe-395b50ad4b66	Identifier that ties this record to an existing wallet
timeout	integer	10	Number of seconds the initial request will wait for a completed record
rule	string	no rule	Rules enforced for this request (future feature)
meta_data	object	null	Metadata for this credential
state	string	offer_sent	Null means no issuance has been triggered yet, likely due to no available connection.
complete	boolean	false	This field does not indicate successful issuance, only that the request record has finished its process.
result	boolean	false	Indicates successful issuance result. This field should be used alongside “complete” to determine successful request record
result_string	string	“Pending”	Custom string for helping to define the state of the request
credential_exchange_id	array	[...]	Contains unique IDs for each issued credential
error	string	“Public DID not set.”	Error message caught while processing request record
created_at	timestamp	2024-12-31T09:34:31.635Z	Date/time this record was created
updated_at	timestamp	2024-12-31T09:34:31.635Z	Date/time this record was last updated

Sample Response Body:

{
    "request_id": 1,
    "connection_id": "cdcff763-5616-4a43-90ee-b0a38e0f6646",
    "contact_id": "",
    "invitation_id": 1,
    "schema_id": "KT4LtL7HEMePqQSyKVof7g:2:Email:1.0",
    "attributes": [
      {
        "name": "local_part",
        "value": "alice"
      },
      {
        "name": "domain",
        "value": "example.com"
      },
      {
        "name": "address",
        "value": "[email protected]"
      },
      {
        "name": "verified_at",
        "value": "1670296277"
      }
    ],
    "wallet_id": "f20823bb-9079-4026-b9dc-a7f410af5141",
    "timeout": 1,
    "rule": "no rule",
    "meta_data": null,
    "state": null,
    "complete": false,
    "result": false,
    "result_string": "Pending",
    "credential_exchange_id": [
      "5d00c38f-cc6a-4f0c-9dd2-3813c0dd8134"
    ],
    "error": "",
    "created_at": "2025-01-03T12:57:35.090Z",
    "updated_at": "2025-01-03T12:57:37.842Z"
  }

Credentials - Read All Credential Records

/api/v1/credentials - GET

This endpoint fetches all Credential records.

Request Body Information:

No request body

Response Body Information:

The response body is an array of records. The following information is the data of each record:

Field name	Expected type/values	Examples	Notes
credential_exchange_id	string	5d00c38f-cc6a-4f0c-9dd2-3813c0dd8134	Primary identifier for the credential record
wallet_id	string	f20823bb-9079-4026-b9dc-a7f410af5141	Identifier that ties this record to an existing wallet
credential_id	string	null	Unique ID for held credentials
revocation_id	string	null	Identifier used for credential revocation
connection_id	string	cdcff763-5616-4a43-90ee-b0a38e0f6646	Unique identifier that ties a connection to this record
state	string	done	Current state of the credential
thread_id	string	a6ab28e8-1576-4174-8083-e52752327057	Thread identifier for the credential
parent_thread_id	string	null	Parent thread identifier for the credential
schema_id	string	KT4LtL7HEMePqQSyKVof7g:2:Email:1.0	Credentials schema
credential_definition_id	string	JCuYYsqY1X2QcYpVrSkQwL:3:CL:151:default	Credential definition generated via the schema_id
revoc_reg_id	string	null	Field used for credential revocation
revoked	boolean	null	Field used for credential revocation
attributes	object	{...}	Credentials attributes and their values
created_at	timestamp	2025-01-03T12:57:37.827Z	Date/time this record was created
updated_at	timestamp	2025-01-03T12:57:37.827Z	Date/time this record was last updated

Sample Response Body:

[
  {
    "credential_exchange_id": "5d00c38f-cc6a-4f0c-9dd2-3813c0dd8134",
    "wallet_id": "f20823bb-9079-4026-b9dc-a7f410af5141",
    "credential_id": null,
    "revocation_id": null,
    "connection_id": "cdcff763-5616-4a43-90ee-b0a38e0f6646",
    "state": "done",
    "thread_id": "a6ab28e8-1576-4174-8083-e52752327057",
    "parent_thread_id": null,
    "schema_id": "KT4LtL7HEMePqQSyKVof7g:2:Email:1.0",
    "credential_definition_id": "JCuYYsqY1X2QcYpVrSkQwL:3:CL:151:default",
    "revoc_reg_id": null,
    "revoked": null,
    "created_at": "2025-01-03T12:57:37.827Z",
    "updated_at": "2025-01-03T13:05:35.231Z",
    "attributes": null
  }
]

Credentials - Read Credential Record By ID

/api/v1/credentials/<credential_definition_id> - GET

This endpoint fetches a Credential record by its credential_definition_id.

Request Body Information:

No Request body

Response Body Information:

Field name	Expected type/values	Examples	Notes
credential_exchange_id	string	5d00c38f-cc6a-4f0c-9dd2-3813c0dd8134	Primary identifier for the credential record
wallet_id	string	f20823bb-9079-4026-b9dc-a7f410af5141	Identifier that ties this record to an existing wallet
credential_id	string	null	Unique ID for held credentials
revocation_id	string	null	Identifier used for credential revocation
connection_id	string	cdcff763-5616-4a43-90ee-b0a38e0f6646	Unique identifier that ties a connection to this record
state	string	done	Current state of the credential
thread_id	string	a6ab28e8-1576-4174-8083-e52752327057	Thread identifier for the credential
parent_thread_id	string	null	Parent thread identifier for the credential
schema_id	string	KT4LtL7HEMePqQSyKVof7g:2:Email:1.0	Credentials schema
credential_definition_id	string	JCuYYsqY1X2QcYpVrSkQwL:3:CL:151:default	Credential definition generated via the schema_id
revoc_reg_id	string	null	Field used for credential revocation
revoked	boolean	null	Field used for credential revocation
attributes	object	{...}	Credential’s attributes and their values
created_at	timestamp	2025-01-03T12:57:37.827Z	Date/time this record was created
updated_at	timestamp	2025-01-03T12:57:37.827Z	Date/time this record was last updated

Sample Response Body:

{
    "credential_exchange_id": "5d00c38f-cc6a-4f0c-9dd2-3813c0dd8134",
    "wallet_id": "f20823bb-9079-4026-b9dc-a7f410af5141",
    "credential_id": null,
    "revocation_id": null,
    "connection_id": "cdcff763-5616-4a43-90ee-b0a38e0f6646",
    "state": "done",
    "thread_id": "a6ab28e8-1576-4174-8083-e52752327057",
    "parent_thread_id": null,
    "schema_id": "KT4LtL7HEMePqQSyKVof7g:2:Email:1.0",
    "credential_definition_id": "JCuYYsqY1X2QcYpVrSkQwL:3:CL:151:default",
    "revoc_reg_id": null,
    "revoked": null,
    "created_at": "2025-01-03T12:57:37.827Z",
    "updated_at": "2025-01-03T13:05:35.231Z",
    "attributes": null
}

DIDs

DIDs - Create New DID

/api/v1/create-did - POST

This endpoint creates a new decentralized identifier (DID).

Request Body Information:

No request body

Response Body Information:

Field name	Expected type/ values	Examples	Notes
did	string	AwUCmb3ahPhiYVaik3wD7	Decentralized identifier
verkey	string	6RCKgJhNz76u98RpzVYMrrXDEgPn3hZ5mvwyJnjvevP	DID’s verkey
posture	string	wallet_only	Posture of the DID
key_type	string	ed25519	Type of key used for the DID
method	string	sov	Method used for generating the DID
metadata	object	{...}	Metadata for the DID

Sample Response Body:

{
  "did": "AwUCmb3ahPhiYVaik3wD7",
  "verkey": "6RCKgJhNz76u98RpzVYMrrXDEgPn3hZ5mvwyJnjvevP",
  "posture": "wallet_only",
  "key_type": "ed25519",
  "method": "sov",
  "metadata": {}
}

DIDs - Set Public DID

/api/v1/set-public-did - POST

This endpoint sets a public decentralized identifier (DID).

Request URL Parameters Information:

Field name	Expected type/ values	Examples	Notes
DID	text	XhvSpiDsLVmStHa19VC4hJ	DID set as public

Request Body Information:

No request body

Sample URLs:

https://your-domain-name.com/api/v1/set-public-did?DID=WSPiMexQfuVrR9wMQbg5F7

Response Body Information:

Field name	Expected type/ values	Examples	Notes
did	string	XhvSpiDsLVmStHa19VC4hJ	DID set as public
verkey	string	HjfSSD6DDPfAME5Th5NTESEoToJgVWqUo7u81euPGX7K	DID’s verkey
posture	string	posted	Posture of the DID
key_type	string	ed25519	Type of key used for the DID
method	string	sov	Method used for generating the DID
metadata	object	{...}	Metadata for the DID

Sample Response Body:

{
  "did": "XhvSpiDsLVmStHa19VC4hJ",
  "verkey": "HjfSSD6DDPfAME5Th5NTESEoToJgVWqUo7u81euPGX7K",
  "posture": "posted",
  "key_type": "ed25519",
  "method": "sov",
  "metadata": {
    "posted": true
  }
}

Email

Email - Verify Email Addresses

/api/v1/emails/verify - POST

This endpoint verifies multiple email addresses using the SMTP configurations.

Request Body Information:

Field name	Expected type/values	Examples	Notes
emails	array	[ {“email”: “[email protected]”} ]	List of emails to verify

Response Body Information:

Field name	Expected type/values	Examples	Notes
success	string	“All emails sent successfully”	Success message

Sample Response Body:

{
    "success": "All emails sent successfully!"
}

Invitations

Invitations - Create New Invitation

/api/v1/invitations - POST

This endpoint creates a new invitation of type OOB or CV1.

Request Body Information:

Field name	Expected type/values	Examples	Notes
invitation_type	text	OOB	CV1 or OOB (Connections v. 1 or Out of Band)
contact_id	text	blank	Optional contact string used for calls that require a known contact
handshake_protocol	text	https://didcomm.org/didexchange/1.1	Protocol used to generate the invitation
alias	text	Acme Issuer	String for how this connection could be labeled in the receiving agent. Technically optional, but probably a bad idea to leave empty
invitation_mode	text	Once	Multi, Once (or "Static," but for developers use only). TODO: Multi requires the use of a multi-use webhook in order for the other APIs to work.
accept	text	Auto	Auto, Manual
public	boolean	false	true or false
invitation_role	text	blank	Optional string describing this connection's role (such as "holder")
invitation_label	text	Create Account	Optional string for naming this invitation in the sending agent
invitation_status	text	blank	Optional; Active, Inactive, Deleted; this is not an ACA-Py field, but allows our controller to utilize invitations intelligently. Defaults to Active
invitation_description	text	blank	Optional string describing the purpose of this invitation
invitation_active_starting_at	timestamp	blank	Optional unix timestamp stating when the controller should begin recognizing this invitation as active. If not provided, set to the current time. Caution, the controller can be bypassed and does not strictly control ACA-Py.
invitation_active_ending_at	timestamp	blank	Optional unix timestamp stating when the controller should stop recognizing this invitation as active. Can be null (doesn't end). Caution, the controller can be bypassed and does not strictly control ACA-Py.
uses_allowed	int	blank	Optional number of uses the controller will allow this invitation. Caution, the controller can be bypassed and does not strictly control ACA-Py.

Sample Request Bodies:

Invitation with connection reuse:

{ 
  "contact_id": "contact123", 
  "handshake_protocol": "https://didcomm.org/didexchange/1.1",
  "invitation_type": "OOB", 
  "invitation_mode": "once", 
  "public": true, 
  "accept": "auto",
  "alias": "API invitation with connection reuse"
  "invitation_role": "Holder",
  "invitation_label": "API Invite",
  "invitation_description": "Invitation created through API", 
  "invitation_status": "active", 
  "invitation_active_starting_at": null, 
  "invitation_active_ending_at": null, 
  "invitation_uses_allowed": null
}

Invitation without connection reuse:

{ 
  "contact_id": "contact123",
  "handshake_protocol": "https://didcomm.org/didexchange/1.1",
  "invitation_type": "OOB", 
  "invitation_mode": "once", 
  "public": false, 
  "accept": "auto",
  "alias": "API invitation without connection reuse"
  "invitation_role": "Holder",
  "invitation_label": "API Invite",
  "invitation_description": "Invitation created through API", 
  "invitation_status": "active", 
  "invitation_active_starting_at": null, 
  "invitation_active_ending_at": null, 
  "invitation_uses_allowed": null
}

Invitation with multi-use:

{ 
  "contact_id": "contact123",
  "handshake_protocol": "https://didcomm.org/didexchange/1.1",
  "invitation_type": "OOB", 
  "invitation_mode": "multi", 
  "public": false, 
  "accept": "auto",
  "alias": "API invitation with multi-use"
  "invitation_role": "Holder",
  "invitation_label": "API Invite", 
  "invitation_description": "Invitation created through API", 
  "invitation_status": "active", 
  "invitation_active_starting_at": null, 
  "invitation_active_ending_at": null, 
  "invitation_uses_allowed": null
}

Response Body Information:

Field name	Expected type/values	Examples	Notes
invitation_url	text	https://proven.mediator.indiciotech.io?oob...	Invitation URL (currently formatted for either connections v. 1 or OOB)
invitation_id	int	37	ID to keep track of this particular invitation
contact_id	text	“contact123”	Contact ID specified during the creation of this invitation

Sample Response Body:

{
  "invitation_url": "https://proven.mediator.indiciotech.io?c_i=...",
  "invitation_id": 37,
  "contact_id": "49"
}

Invitations - Accept Invitation

/api/v1/invitations/accept - POST

This endpoint accepts an invitation of type CV1 or OOB.

Request Body Information

Field name	Expected type/values	Examples	Notes
invitation_url	text	https://proven.mediator.indiciotech.io?oob...	Properly encoded connections v. 1 or OOB invitation

Sample Request Body:

{ 
  "invitation_url": "https://proven.mediator.indiciotech.io?c_i...",   
}

Response Body Information:

Field name	Expected type/values	Examples	Notes
success	boolean	true	Signals successful invitation acceptance
invitation_record	object	{...}	Invitation record data object

Sample Response Body:

{
  "success": true,
  "invitation_record": {
      "state": "deleted",
      "created_at": "2024-12-30T10:37:30.751037Z",
      "updated_at": "2024-12-30T10:37:30.751037Z",
      "trace": false,
      "oob_id": "2f5ce0d7-dfd4-4aef-871f-eb0a522a2f52",
      "invi_msg_id": "afbc12b7-28fa-4936-bf11-748148a98ffc",
      "invitation": {...},
      "connection_id": "65eb5586-e519-441d-a05c-c3c697ecd97a",
      "role": "receiver",
      "multi_use": false
  }
}

Invitations - Read All Invitations

/api/v1/invitations - GET

This endpoint fetches all invitations, and includes parameters for pagination purposes.

Requests URL Parameters Information:

URL parameters should be hyphen-separated in case they ever interact with a system that needs to be search-engine-indexed.

Field name	Expected type/values	Examples	Notes
sort-field	text	contact_id	Optional, any of the field names listed in the "Create invitation" POST body plus invitation_id
sort-direction	text	ASC	Optional, ASC or DESC
page-size	int	10	Optional, how many items should be returned in a page
current-page	int	2	Optional, the current page to retrieve
item-count	int	10	Optional, the total number of items

Sample URLs:

https://your-domain-name.com/api/v1/invitations?sort-field=contact_id&sort-direction=ASC&page-size=10&current-page=2

https://your-domain-name.com/api/v1/invitations?page-size=50&current-page=5

Response Body Information:

The Response Body has three sections:

• Params: The pagination and sorting parameters:

  • "sort": “DESC”

  • pageSize": "10"

  • "currentPage": 1

  • "pageCount": 1

  • "itemCount": 1

• Rows: The array of invitations

  • Each row in the rows array has the properties found in the table below.

• Count: The number of items returned:

  • “count”: 1

Field name	Expected type/values	Examples	Notes
invitation_id	int	4325	Integer used as the primary identifier for this record
oob_id	text	db6da148-33ee-4108-96d9-f39bee835981	ID used to identify an Out of Band (OOB) connection
contact_id	text	contact123	Contact ID string
connection_id	text	db6da148-33ee-4108-96d9-f39bee835981	ID used to identify a CV1 connection
my_did	text	did:sov:<did>	Public DID (empty if invitation is not public)
alias	text	Acme Issuer	String for how this connection should be "named"
invitation_key	text	did:key:<...>	Invitation Key managed by agent
invitation_mode	text	Once	Multi, Once (or "Static," but for developers use only)
invitation_url	text	https://<domain>?oob=<base64 invitation>	Invitation URL (CV1 or OOB)
invitation_msg_id	text	afbc12b7-28fa-4936-bf11-748148a98ffc	Unique Identifier for invitation exchange
invitation	obj	{...}	Invitation data object
wallet_id	text	eea19d5b-cbfc-44a0-9406-a9bddcbe3994	Identifier for the wallet the invitation belongs to
accept	text	auto	auto, manual
their_role	text	sender	Role of agent that generated the invitation
their_label	text	Primary Wallet	Label of agent/wallet that generated the invitation
service_endpoint	text	https://hard-tiger-38.tun2.indiciotech.io	Endpoint used for serving the Invitation URL
domain	text	hard-tiger-38.tun2.indiciotech.io	Domain parsed from service_endpoint
path	text	/path	Path parsed from service_endpoint
workflow_status	text	active	active, inactive (managed by controller)
state	text	deleted	State of the invitation (managed by ACA-Py agent)
description	text	General purpose issuer	Optional string describing the purpose of this invitation
active_starting_at	timestamp	2024-12-30T10:36:52.443Z	Optional unix timestamp stating when the controller should begin recognizing this invitation as active. If not provided, set to the current time. Caution, the controller can be bypassed and does not strictly control ACA-Py.
active_ending_at	timestamp	null	Optional unix timestamp stating when the controller should stop recognizing this invitation as active. Can be null (doesn't end). Caution, the controller can be bypassed and does not strictly control ACA-Py.
uses_allowed	int	100	Optional number of uses the controller will allow for this invitation. Caution, the controller can be bypassed and does not strictly control ACA-Py. The null value signals an infinite use invitation.
uses_total	int	43	Number of times this invitation has been used
created_at	timestamp	"2024-12-30T10:36:52.466Z"	Date of creation for the invitation record (controller level)
updated_at	timestamp	"2024-12-30T10:36:52.466Z"	Date the invitation record was last updated (controller level)

Sample Response Body:

{
  "params": {
      "sort": [
          [
              [
                  "updated_at",
                  "DESC"
              ]
          ]
      ],
      "pageSize": "10",
      "currentPage": 1,
      "pageCount": 1,
      "itemCount": 1
  },
  "rows": [
      {
          "invitation_id": 1,
          "oob_id": "c2e4e2d2-eb01-4065-94e3-6d4c0e17d537",
          "contact_id": "199e022b-bb4c-4ae4-99fe-395b50ad4b66",
          "connection_id": "f7699aa9-beec-4e0c-868d-eb3766ad2f64",
          "my_did": "",
          "alias": "Proven",
          "invitation_key": "did:key:z6MkkhftQjNAzNGYw9vSTKWnkdEQMRdzpXToAwwp4QtbRPSV#z6MkkhftQjNAzNGYw9vSTKWnkdEQMRdzpXToAwwp4QtbRPSV",
          "invitation_mode": "once",
          "invitation_url": "https://hard-tiger-38.tun2.indiciotech.io?oob=eyJAdHlwZSI6ICJodHRwczovL2RpZGNvbW0ub3JnL291dC1vZi1iYW5kLzEuMS9pbnZpdGF0aW9uIiwgIkBpZCI6ICJhZmJjMTJiNy0yOGZhLTQ5MzYtYmYxMS03NDgxNDhhOThmZmMiLCAibGFiZWwiOiAiUHJpbWFyeVdhbGxldCIsICJoYW5kc2hha2VfcHJvdG9jb2xzIjogWyJodHRwczovL2RpZGNvbW0ub3JnL2RpZGV4Y2hhbmdlLzEuMCJdLCAic2VydmljZXMiOiBbeyJpZCI6ICIjaW5saW5lIiwgInR5cGUiOiAiZGlkLWNvbW11bmljYXRpb24iLCAicmVjaXBpZW50S2V5cyI6IFsiZGlkOmtleTp6Nk1ra2hmdFFqTkF6TkdZdzl2U1RLV25rZEVRTVJkenBYVG9Bd3dwNFF0YlJQU1YjejZNa2toZnRRak5Bek5HWXc5dlNUS1dua2RFUU1SZHpwWFRvQXd3cDRRdGJSUFNWIl0sICJzZXJ2aWNlRW5kcG9pbnQiOiAiaHR0cHM6Ly9oYXJkLXRpZ2VyLTM4LnR1bjIuaW5kaWNpb3RlY2guaW8ifV19",
          "invitation_msg_id": "afbc12b7-28fa-4936-bf11-748148a98ffc",
          "invitation": {...},
          "wallet_id": "eea19d5b-cbfc-44a0-9406-a9bddcbe3994",
          "accept": "auto",
          "their_role": "sender",
          "their_label": "PrimaryWallet",
          "service_endpoint": "https://hard-tiger-38.tun2.indiciotech.io",
          "domain": "hard-tiger-38.tun2.indiciotech.io",
          "path": "",
          "workflow_status": "inactive",
          "state": "deleted",
          "description": "",
          "active_starting_at": "2024-12-30T10:36:52.443Z",
          "active_ending_at": n

Invitations - Read Invitation by ID

/api/v1/invitations/<invitation_id> - GET

This endpoint fetches a single invitation record by its invitation_id.

Request Body Information:

No Request Body

Response Body Information:

Field name	Expected type/values	Examples	Notes
invitation_id	int	4325	Integer used as the primary identifier for this record
oob_id	text	db6da148-33ee-4108-96d9-f39bee835981	ID used to identify an Out of Band (OOB) connection
contact_id	text	contact123	Contact ID string
connection_id	text	db6da148-33ee-4108-96d9-f39bee835981	ID used to identify a CV1 connection
my_did	text	did:sov:<did>	Public DID (empty if invitation is not public)
alias	text	Acme Issuer	String for how this connection should be "named"
invitation_key	text	did:key:<...>	Invitation Key managed by agent
invitation_mode	text	Once	Multi, Once (or "Static," but for developers use only)
invitation_url	text	https://<domain>?oob=<base64 invitation>	Invitation URL (CV1 or OOB)
invitation_msg_id	text	afbc12b7-28fa-4936-bf11-748148a98ffc	Unique Identifier for invitation exchange
invitation	obj	{...}	Invitation data object
wallet_id	text	eea19d5b-cbfc-44a0-9406-a9bddcbe3994	Identifier for the wallet the invitation belongs to
accept	text	auto	auto, manual
their_role	text	sender	Role of the agent that generated the invitation
their_label	text	Primary Wallet	Label of the agent/wallet that generated the invitation
service_endpoint	text	https://hard-tiger-38.tun2.indiciotech.io	Endpoint used for serving the Invitation URL
domain	text	hard-tiger-38.tun2.indiciotech.io	Domain parsed from service_endpoint
path	text	/path	Path parsed from service_endpoint
workflow_status	text	active	active, inactive (managed by controller)
state	text	deleted	State of the invitation (managed by ACA-Py agent)
description	text	General purpose issuer	Optional string describing the purpose of this invitation
active_starting_at	timestamp	2024-12-30T10:36:52.443Z	Optional unix timestamp stating when the controller should begin recognizing this invitation as active. If not provided, set to the current time. Caution, the controller can be bypassed and does not strictly control ACA-Py.
active_ending_at	timestamp	null	Optional unix timestamp stating when the controller should stop recognizing this invitation as active. Can be null (doesn't end). Caution, the controller can be bypassed and does not strictly control ACA-Py.
uses_allowed	int	100	Optional number of uses the controller will allow for this invitation. Caution, the controller can be bypassed and does not strictly control ACA-Py. The null value signals an infinite use invitation.
uses_total	int	43	Number of times this invitation has been used
created_at	timestamp	"2024-12-30T10:36:52.466Z"	Date of creation for the invitation record (controller level)
updated_at	timestamp	"2024-12-30T10:36:52.466Z"	Date the invitation record was last updated (controller level)

Sample Response Body:

{
  "invitation_id": 1,
  "oob_id": "c2e4e2d2-eb01-4065-94e3-6d4c0e17d537",
  "contact_id": "199e022b-bb4c-4ae4-99fe-395b50ad4b66",
  "connection_id": "f7699aa9-beec-4e0c-868d-eb3766ad2f64",
  "my_did": "",
  "alias": "Proven",
  "invitation_key": "did:key:z6MkkhftQjNAzNGYw9vSTKWnkdEQMRdzpXToAwwp4QtbRPSV#z6MkkhftQjNAzNGYw9vSTKWnkdEQMRdzpXToAwwp4QtbRPSV",
  "invitation_mode": "once",
  "invitation_url": "https://hard-tiger-38.tun2.indiciotech.io?oob=eyJAdHlwZSI6ICJodHRwczovL2RpZGNvbW0ub3JnL291dC1vZi1iYW5kLzEuMS9pbnZpdGF0aW9uIiwgIkBpZCI6ICJhZmJjMTJiNy0yOGZhLTQ5MzYtYmYxMS03NDgxNDhhOThmZmMiLCAibGFiZWwiOiAiUHJpbWFyeVdhbGxldCIsICJoYW5kc2hha2VfcHJvdG9jb2xzIjogWyJodHRwczovL2RpZGNvbW0ub3JnL2RpZGV4Y2hhbmdlLzEuMCJdLCAic2VydmljZXMiOiBbeyJpZCI6ICIjaW5saW5lIiwgInR5cGUiOiAiZGlkLWNvbW11bmljYXRpb24iLCAicmVjaXBpZW50S2V5cyI6IFsiZGlkOmtleTp6Nk1ra2hmdFFqTkF6TkdZdzl2U1RLV25rZEVRTVJkenBYVG9Bd3dwNFF0YlJQU1YjejZNa2toZnRRak5Bek5HWXc5dlNUS1dua2RFUU1SZHpwWFRvQXd3cDRRdGJSUFNWIl0sICJzZXJ2aWNlRW5kcG9pbnQiOiAiaHR0cHM6Ly9oYXJkLXRpZ2VyLTM4LnR1bjIuaW5kaWNpb3RlY2guaW8ifV19",
  "invitation_msg_id": "afbc12b7-28fa-4936-bf11-748148a98ffc",
  "invitation": {
      "@type": "https://didcomm.org/out-of-band/1.1/invitation",
      "@id": "afbc12b7-28fa-4936-bf11-748148a98ffc",
      "label": "PrimaryWallet",
      "handshake_protocols": [
          "https://didcomm.org/didexchange/1.0"
      ],
      "services": [
          {
              "id": "#inline",
              "type": "did-communication",
              "recipientKeys": [
                  "did:key:z6MkkhftQjNAzNGYw9vSTKWnkdEQMRdzpXToAwwp4QtbRPSV#z6MkkhftQjNAzNGYw9vSTKWnkdEQMRdzpXToAwwp4QtbRPSV"
              ],
              "serviceEndpoint": "https://hard-tiger-38.tun2.indiciotech.io"
          }
      ]
  },
  "wallet_id": "eea19d5b-cbfc-44a0-9406-a9bddcbe3994",
  "accept": "auto",
  "their_role": "sender",
  "their_label": "PrimaryWallet",
  "service_endpoint": "https://hard-tiger-38.tun2.indiciotech.io",
  "domain": "hard-tiger-38.tun2.indiciotech.io",
  "path": "",
  "workflow_status": "inactive",
  "state": "deleted",
  "description": "",
  "active_starting_at": "2024-12-30T10:36:52.443Z",
  "active_ending_at": null,
  "uses_allowed": 1,
  "uses_total": 1,
  "created_at": "2024-12-30T10:36:52.466Z",
  "updated_at": "2024-12-30T10:37:31.732Z"
}

Invitations - Update Invitation Record

/api/v1/invitations/<invitation_id> - PUT

This endpoint updates an existing invitation record by using its invitation_id.

Request Body Information:

The following fields can be selectively provided:

Field name	Expected type/values	Examples	Notes
workflow_status	string	inactive	Controls usage and availability of invitation (controller level only)
description	string	Updating invitation description via API	Invitation’s general use description
active_starting_at	timestamp	2024-12-30T10:36:52.466Z	Controls invitation’s workflow_status (active or inactive) (controller level only)
active_ending_at	string	2025-12-30T10:36:52.466Z	Controls invitation’s workflow_status (active or inactive) (controller level only)
uses_allowed	integer	20	Limits the usage of multi-use invitations. Single-use invitations default to 1 and cannot be updated (controller level only).

Response Body Information:

Field name	Expected type/values	Examples	Notes
invitation_id	int	4325	Integer used as the primary identifier for this record
oob_id	text	db6da148-33ee-4108-96d9-f39bee835981	ID used to identify an Out of Band (OOB) connection
contact_id	text	contact123	Contact ID string
connection_id	text	db6da148-33ee-4108-96d9-f39bee835981	ID used to identify a CV1 connection
my_did	text	did:sov:<did>	Public DID (empty if invitation is not public)
alias	text	Acme Issuer	String for how this connection should be "named" or referred to, especially in the UI
invitation_key	text	did:key:<...>	Invitation Key managed by agent
invitation_mode	text	Once	Multi, Once (or "Static," but for developers use only)
invitation_url	text	https://<domain>?oob=<base64 invitation>	Invitation URL (CV1 or OOB)
invitation_msg_id	text	afbc12b7-28fa-4936-bf11-748148a98ffc	Unique Identifier for invitation exchange
invitation	obj	{...}	Invitation data object
wallet_id	text	eea19d5b-cbfc-44a0-9406-a9bddcbe3994	Identifier for the wallet the invitation belongs to
accept	text	auto	auto, manual
their_role	text	sender	Role of agent that generated the invitation
their_label	text	Primary Wallet	Label of agent/wallet that generated the invitation
service_endpoint	text	https://hard-tiger-38.tun2.indiciotech.io	Endpoint used for serving the Invitation URL
domain	text	hard-tiger-38.tun2.indiciotech.io	Domain parsed from service_endpoint
path	text	/path	Path parsed from service_endpoint
workflow_status	text	active	active, inactive (managed by controller)
state	text	deleted	State of the invitation (managed by ACA-Py agent)
description	text	General purpose issuer	Optional string describing the purpose of this invitation
active_starting_at	timestamp	2024-12-30T10:36:52.443Z	Optional unix timestamp stating when the controller should begin recognizing this invitation as active. If not provided, set to the current time. Caution, the controller can be bypassed and does not strictly control ACA-Py.
active_ending_at	timestamp	null	Optional unix timestamp stating when the controller should stop recognizing this invitation as active. Can be null (does not end). Caution, the controller can be bypassed and does not strictly control ACA-Py.
uses_allowed	int	100	Optional number of uses the controller will allow for this invitation. Caution, the controller can be bypassed and does not strictly control ACA-Py. The null value signals an infinite use invitation.
uses_total	int	43	Number of times this invitation has been used
created_at	timestamp	"2024-12-30T10:36:52.466Z"	Date of creation for the invitation record (controller level)
updated_at	timestamp	"2024-12-30T10:36:52.466Z"	Date the invitation record was last updated (controller level)

Sample Response Body:

{
  "invitation_id": 1,
  "oob_id": "c2e4e2d2-eb01-4065-94e3-6d4c0e17d537",
  "contact_id": "199e022b-bb4c-4ae4-99fe-395b50ad4b66",
  "connection_id": "f7699aa9-beec-4e0c-868d-eb3766ad2f64",
  "my_did": "",
  "alias": "Proven",
  "invitation_key": "did:key:z6MkkhftQjNAzNGYw9vSTKWnkdEQMRdzpXToAwwp4QtbRPSV#z6MkkhftQjNAzNGYw9vSTKWnkdEQMRdzpXToAwwp4QtbRPSV",
  "invitation_mode": "once",
  "invitation_url": "https://hard-tiger-38.tun2.indiciotech.io?oob=eyJAdHlwZSI6ICJodHRwczovL2RpZGNvbW0ub3JnL291dC1vZi1iYW5kLzEuMS9pbnZpdGF0aW9uIiwgIkBpZCI6ICJhZmJjMTJiNy0yOGZhLTQ5MzYtYmYxMS03NDgxNDhhOThmZmMiLCAibGFiZWwiOiAiUHJpbWFyeVdhbGxldCIsICJoYW5kc2hha2VfcHJvdG9jb2xzIjogWyJodHRwczovL2RpZGNvbW0ub3JnL2RpZGV4Y2hhbmdlLzEuMCJdLCAic2VydmljZXMiOiBbeyJpZCI6ICIjaW5saW5lIiwgInR5cGUiOiAiZGlkLWNvbW11bmljYXRpb24iLCAicmVjaXBpZW50S2V5cyI6IFsiZGlkOmtleTp6Nk1ra2hmdFFqTkF6TkdZdzl2U1RLV25rZEVRTVJkenBYVG9Bd3dwNFF0YlJQU1YjejZNa2toZnRRak5Bek5HWXc5dlNUS1dua2RFUU1SZHpwWFRvQXd3cDRRdGJSUFNWIl0sICJzZXJ2aWNlRW5kcG9pbnQiOiAiaHR0cHM6Ly9oYXJkLXRpZ2VyLTM4LnR1bjIuaW5kaWNpb3RlY2guaW8ifV19",
  "invitation_msg_id": "afbc12b7-28fa-4936-bf11-748148a98ffc",
  "invitation": {
      "@type": "https://didcomm.org/out-of-band/1.1/invitation",
      "@id": "afbc12b7-28fa-4936-bf11-748148a98ffc",
      "label": "PrimaryWallet",
      "handshake_protocols": [
          "https://didcomm.org/didexchange/1.0"
      ],
      "services": [
          {
              "id": "#inline",
              "type": "did-communication",
              "recipientKeys": [
                  "did:key:z6MkkhftQjNAzNGYw9vSTKWnkdEQMRdzpXToAwwp4QtbRPSV#z6MkkhftQjNAzNGYw9vSTKWnkdEQMRdzpXToAwwp4QtbRPSV"
              ],
              "serviceEndpoint": "https://hard-tiger-38.tun2.indiciotech.io"
          }
      ]
  },
  "wallet_id": "eea19d5b-cbfc-44a0-9406-a9bddcbe3994",
  "accept": "auto",
  "their_role": "sender",
  "their_label": "PrimaryWallet",
  "service_endpoint": "https://hard-tiger-38.tun2.indiciotech.io",
  "domain": "hard-tiger-38.tun2.indiciotech.io",
  "path": "",
  "workflow_status": "inactive",
  "state": "deleted",
  "description": "Updating invitation description via API",
  "active_starting_at": "2024-12-30T10:36:52.443Z",
  "active_ending_at": null,
  "uses_allowed": 1,
  "uses_total": 1,
  "created_at": "2024-12-30T10:36:52.466Z",
  "updated_at": "2024-12-30T10:37:31.732Z"
}

Invitations - Delete Invitation

/api/v1/invitations/<invitation_id> - DELETE

This endpoint deletes an invitation record by providing its invitation_id.

Response Body Information:

Field name	Expected type/values	Examples	Notes
success	string	“Invitation 2 was deleted successfully!”	Success message

Sample Response Body:

{
  "success": "Invitation 2 was deleted successfully!"
}

Presentations

Presentations - Read All Presentations

/api/v1/presentations - GET

This endpoint fetches all presentation records.

Request Body Information:

No Request Body

Response Body Information:

The response body is an array of records. The following information is the data of each record:

Field name	Expected type/values	Examples	Notes
presentation_exchange_id	string	349c7662-6837-4274-b213-355dab5d92f2	Primary identifier used for the presentation record
wallet_id	string	f20823bb-9079-4026-b9dc-a7f410af5141	Identifier that ties this record to an existing wallet
trace	boolean	false	Not used at present
connection_id	string	cdcff763-5616-4a43-90ee-b0a38e0f6646	Unique identifier used for tying a connection to the presentation record
role	string	verifier	Role of the presentation
verified	boolean	true	Indicates a verified presentation
presentation_created_at	timestamp	2025-01-06T10:16:26.561Z	ACA-Py field
presentation_updated_at	timestamp	2025-01-06T10:16:26.561Z	ACA-Py field
presentation_request_dict	object	{...}	ACA-Py field
initiator	string	self	Initiator of the presentation
presentation_request	object	{...}	Request object of the presentation
state	string	request-sent	Current state of the presentation
thread_id	string	85e6c895-be08-4c1d-be5d-91ccd902b62c	Thread identifier for the presentation
auto_present	boolean	false	Parameter for automatically presenting the presentation
presentation	object	null	Main presentation data
contact_label	string	Alice Smith	Contact label for the presentation
contact_id	string	contact123	Identifier that ties the presentation to a contact
created_at	timestamp	2025-01-06T10:16:26.647Z	Date/time this record was created
updated_at	timestamp	2025-01-06T10:16:26.647Z	Date/time this record was last updated

Sample Response Body:

[
  {
    "presentation_exchange_id": "349c7662-6837-4274-b213-355dab5d92f2",
    "wallet_id": "f20823bb-9079-4026-b9dc-a7f410af5141",
    "trace": false,
    "connection_id": "cdcff763-5616-4a43-90ee-b0a38e0f6646",
    "role": "verifier",
    "verified": false,
    "presentation_created_at": "2025-01-06T10:16:26.561Z",
    "presentation_updated_at": "2025-01-06T10:16:26.561Z",
    "presentation_request_dict": {
      "@type": "https://didcomm.org/present-proof/2.0/request-presentation",
      "@id": "85e6c895-be08-4c1d-be5d-91ccd902b62c",
      "comment": "Requesting Presentation v2.0",
      "will_confirm": true,
      "formats": [
        {
          "attach_id": "indy",
          "format": "hlindy/[email protected]"
        }
      ],
      "request_presentations~attach": [
        {
          "@id": "indy",
          "mime-type": "application/json",
          "data": {
            "base64": "eyJuYW1lIjogIlByb29mIFJlcXVlc3QgdjIiLCAibm9uY2UiOiAiMTQ0MTI3ODcxMzAxMjI1NTU3MTQzNTcyMjUxODkxNjk4MDIyMTE1OTM4MTA1MTY1MjI3MTQ0MjAyMzYyNDM0OTI0MTMxMTA4MjAyNTYyMDMxMzQzNDY1ODEwODIyOTc4ODIxMCIsICJyZXF1ZXN0ZWRfcHJlZGljYXRlcyI6IHt9LCAicmVxdWVzdGVkX2F0dHJpYnV0ZXMiOiB7IjljOGM5YTVlLTg4YzctNGIxNy05ODk4LTExYzVhMTZiNzRjNiI6IHsibmFtZXMiOiBbInZlcmlmaWVkX2F0IiwgImxvY2FsX3BhcnQiLCAiYWRkcmVzcyIsICJkb21haW4iXSwgInJlc3RyaWN0aW9ucyI6IFt7InNjaGVtYV9pZCI6ICJLVDRMdEw3SEVNZVBxUVN5S1ZvZjdnOjI6RW1haWw6MS4wIn1dfX0sICJ2ZXJzaW9uIjogIjEuMCJ9"
          }
        }
      ]
    },
    "initiator": "self",
    "presentation_request": {
      "name": "Proof Request v2",
      "nonce": "1441278713012255571435722518916980221159381051652271442023624349241311082025620313434658108229788210",
      "requested_predicates": {},
      "requested_attributes": {
        "9c8c9a5e-88c7-4b17-9898-11c5a16b74c6": {
          "names": [
            "verified_at",
            "local_part",
            "address",
            "domain"
          ],
          "restrictions": [
            {
              "schema_id": "KT4LtL7HEMePqQSyKVof7g:2:Email:1.0"
            }
          ]
        }
      },
      "version": "1.0"
    },
    "state": "request-sent",
    "thread_id": "85e6c895-be08-4c1d-be5d-91ccd902b62c",
    "auto_present": false,
    "presentation": null,
    "contact_label": "Alice Smith",
    "contact_id": "90c98aa3-5ef4-4f1a-8107-05cc0b08ed8b",
    "created_at": "2025-01-06T10:16:26.647Z",
    "updated_at": "2025-01-06T10:16:26.647Z"
  }
]

Presentations - Read Presentation by ID

/api/v1/presentations/<presentation_exchange_id> - GET

This endpoint fetches a presentation record by its presentation_exchange_id.

Response Body Information:

Field name	Expected type/values	Examples	Notes
presentation_exchange_id	string	349c7662-6837-4274-b213-355dab5d92f2	Primary identifier used for the presentation record
wallet_id	string	f20823bb-9079-4026-b9dc-a7f410af5141	Identifier that ties this record to an existing wallet
trace	boolean	false	Not used at present
connection_id	string	cdcff763-5616-4a43-90ee-b0a38e0f6646	Unique identifier used for tying a connection to the presentation record
role	string	verifier	Role of the presentation
verified	boolean	true	Indicates a verified presentation
presentation_created_at	timestamp	2025-01-06T10:16:26.561Z	ACA-Py field
presentation_updated_at	timestamp	2025-01-06T10:16:26.561Z	ACA-Py field
presentation_request_dict	object	{...}	ACA-Py field
initiator	string	self	Initiator of the presentation
presentation_request	object	{...}	Request object of the presentation
state	string	request-sent	Current state of the presentation
thread_id	string	85e6c895-be08-4c1d-be5d-91ccd902b62c	Thread identifier for the presentation
auto_present	boolean	false	Parameter for automatically presenting the presentation
presentation	object	null	Main presentation data
contact_label	string	Alice Smith	Contact label for the presentation
contact_id	string	contact123	Identifier that ties the presentation to a contact
created_at	timestamp	2025-01-06T10:16:26.647Z	Date/time this record was created
updated_at	timestamp	2025-01-06T10:16:26.647Z	Date/time this record was last updated

Sample Response Body:

{
    "presentation_exchange_id": "349c7662-6837-4274-b213-355dab5d92f2",
    "wallet_id": "f20823bb-9079-4026-b9dc-a7f410af5141",
    "trace": false,
    "connection_id": "cdcff763-5616-4a43-90ee-b0a38e0f6646",
    "role": "verifier",
    "verified": false,
    "presentation_created_at": "2025-01-06T10:16:26.561Z",
    "presentation_updated_at": "2025-01-06T10:16:26.561Z",
    "presentation_request_dict": {
      "@type": "https://didcomm.org/present-proof/2.0/request-presentation",
      "@id": "85e6c895-be08-4c1d-be5d-91ccd902b62c",
      "comment": "Requesting Presentation v2.0",
      "will_confirm": true,
      "formats": [
        {
          "attach_id": "indy",
          "format": "hlindy/[email protected]"
        }
      ],
      "request_presentations~attach": [
        {
          "@id": "indy",
          "mime-type": "application/json",
          "data": {
            "base64": "eyJuYW1lIjogIlByb29mIFJlcXVlc3QgdjIiLCAibm9uY2UiOiAiMTQ0MTI3ODcxMzAxMjI1NTU3MTQzNTcyMjUxODkxNjk4MDIyMTE1OTM4MTA1MTY1MjI3MTQ0MjAyMzYyNDM0OTI0MTMxMTA4MjAyNTYyMDMxMzQzNDY1ODEwODIyOTc4ODIxMCIsICJyZXF1ZXN0ZWRfcHJlZGljYXRlcyI6IHt9LCAicmVxdWVzdGVkX2F0dHJpYnV0ZXMiOiB7IjljOGM5YTVlLTg4YzctNGIxNy05ODk4LTExYzVhMTZiNzRjNiI6IHsibmFtZXMiOiBbInZlcmlmaWVkX2F0IiwgImxvY2FsX3BhcnQiLCAiYWRkcmVzcyIsICJkb21haW4iXSwgInJlc3RyaWN0aW9ucyI6IFt7InNjaGVtYV9pZCI6ICJLVDRMdEw3SEVNZVBxUVN5S1ZvZjdnOjI6RW1haWw6MS4wIn1dfX0sICJ2ZXJzaW9uIjogIjEuMCJ9"
          }
        }
      ]
    },
    "initiator": "self",
    "presentation_request": {
      "name": "Proof Request v2",
      "nonce": "1441278713012255571435722518916980221159381051652271442023624349241311082025620313434658108229788210",
      "requested_predicates": {},
      "requested_attributes": {
        "9c8c9a5e-88c7-4b17-9898-11c5a16b74c6": {
          "names": [
            "verified_at",
            "local_part",
            "address",
            "domain"
          ],
          "restrictions": [
            {
              "schema_id": "KT4LtL7HEMePqQSyKVof7g:2:Email:1.0"
            }
          ]
        }
      },
      "version": "1.0"
    },
    "state": "request-sent",
    "thread_id": "85e6c895-be08-4c1d-be5d-91ccd902b62c",
    "auto_present": false,
    "presentation": null,
    "contact_label": "Alice Smith",
    "contact_id": "90c98aa3-5ef4-4f1a-8107-05cc0b08ed8b",
    "created_at": "2025-01-06T10:16:26.647Z",
    "updated_at": "2025-01-06T10:16:26.647Z"
  }

TAA

TAA - Fetch the TAA

/api/v1/fetch-taa - POST

This endpoint fetches the Transaction Author Agreement (TAA) from the ledger configured in the Proven environment (.env) file.

Request Body Information:

No Request Body

Response Body Information:

Field name	Expected type/values	Examples	Notes
aml_record	object	{...}	(Acceptance Mechanism List) Recognized by the network for use in the TAA
taa_record	object	{...}	Main TAA data
taa_required	boolean	true	Indicates a required TAA
taa_accepted	object	{...}	Includes data about the accepted TAA (mechanism, time)

Sample Response Body:

{
  "aml_record": {
    "aml": {...},
    "amlContext": "...",
    "version": "1.0"
  },
  "taa_record": {
    "digest": "...",
    "ratification_ts": ...,
    "text": "...",
    "version": "1.3"
  },
  "taa_required": true,
  "taa_accepted": null
}

TAA - Accept TAA

/api/v1/accept-taa - POST

This endpoint accepts the Transaction Author Agreement (TAA) using the provided TAA data.

Request Body Information:

Field name	Expected type/values	Examples	Notes
mechanism	string	“on_file”	Mechanism used for the TAA
text	string	“Indicio Transaction Author Agreement….”	Transaction Author Agreement
version	string	1.3	Version of the Transaction Author Agreement

Response Body Information:

Field name	Expected type/values	Examples	Notes
aml_record	object	{...}	(Acceptance Mechanism List) Recognized by the network for use in the TAA
taa_record	object	{...}	Main TAA data
taa_required	boolean	true	Indicates a required TAA
taa_accepted	object	{...}	Includes data about the accepted TAA (mechanism, time)

Sample Response Body:

{
  "aml_record": {
    "aml": {...},
    "amlContext": "...",
    "version": "1.0"
  },
  "taa_record": {
    "digest": "...",
    "ratification_ts": ...,
    "text": "...",
    "version": "1.3"
  },
  "taa_required": true,
  "taa_accepted": {...}

Verifications

Verifications - Create Verification Request (AnonCred)

/api/v1/verifications - POST

This endpoint creates a Verification (AnonCred) request record that handles verifying credentials for currently active connection(s) or future active connection(s) until the request record reaches a completed state.

Request Body Information:

Field name	Expected type/values	Examples	Notes
invitation_id	integer	123	Optional integer used to process the request record by a connection tied to the invitation_id. Used with contact_id, has second priority
contact_id	string	contact123	Optional contact ID string used for processing the request record by known contact. Used with invitation_id, has first priority
schemas	array	[{...}, {...}]	Contains schema IDs and their attributes
timeout	integer	10	Number of seconds the initial request will wait for a completed record before responding
rule	string	“no rule”	Rules for this verification request

Sample Request Bodies:

{
  "invitation_id": 1,
  "contact_id": "",
  "schemas": [
    {
      "schema_id": "Bo6yctq8hivGZWyaZcneJf:2:User:1.0",
      "schema_attributes": [
        "Username"
      ]
    }
  ],
  "timeout": "15",
  "rule": "no rule"
}

{
  "invitation_id": 1,
  "contact_id": "123",
  "schemas": [
    {
      "schema_attributes": {
        "domain": {
          "restrictions": [
            {
              "schema_id": "KT4LtL7HEMePqQSyKVof7g:2:Email:1.0"
            }
          ]
        },
        "address": {
          "restrictions": [
            {}
          ]
        },
        "age": {
          "restrictions": []
        },
        "race": {}
      }
    }
  ],
  "timeout": "15",
  "rule": "no rule"
}

Response Body Information:

The response body is an array of records. The following information is the data of each record:

Field name	Expected type/values	Examples	Notes
verification_id	integer	10	Primary identifier for the verification request record
connection_id	string	e2aed3c4-c0a1-4711-902e-f0a9eba618da	Identifier that ties the used connection to the verification request record
contact_id	string	contact123	Optional contact ID string used for processing the request record by known contact. Used with invitation_id, has first priority
invitation_id	integer	123	Optional integer used to process the request record by a connection tied to the invitation_id. Used with contact_id, has second priority
schema_id	string	null	Schema used for the verification request
schema_attributes	object	{...}	Contains the schema attributes and their restrictions, if any are provided
wallet_id	string	407e6215-17c5-4c81-901e-d75d9cc1a75a	Identifier that ties this record to an existing wallet
timeout	integer	10	Number of seconds the initial request waited for a completed request record
rule	string	“no rule”	Rules for the verification request
meta_data	object	null	Metadata for the verification request record
state	string	done	Current state of the verification
complete	boolean	true	This field does not indicate a verified presentation, only that the request record has finished its process.
result	boolean	true	Indicates a verified presentation. This field should be used alongside “complete” to determine a successful request record.
result_string	string	Verified	Custom string for helping to define the state of the request
result_data	array	[...]	Contains the verified attributes
presentation_exchange_id	array	[...]	Contains unique IDs for each proof request
error	string	“Public DID not set.”	Error message caught while processing the request record
created_at	timestamp	2025-01-06T11:51:10.169Z	Date/time this record was created
updated_at	timestamp	2025-01-06T11:51:10.169Z	Date/time this record was last updated

Sample Response Body:

[
  {
    "verification_id": 1,
    "connection_id": "e2aed3c4-c0a1-4711-902e-f0a9eba618da",
    "contact_id": "",
    "invitation_id": 1,
    "schema_id": null,
    "schema_attributes": {
      "Username": {
        "restrictions": [
          {
            "schema_id": "Bo6yctq8hivGZWyaZcneJf:2:User:1.0"
          }
        ]
      }
    },
    "wallet_id": "407e6215-17c5-4c81-901e-d75d9cc1a75a",
    "timeout": 15,
    "rule": "no rule",
    "meta_data": null,
    "state": "done",
    "complete": true,
    "result": true,
    "result_string": "Verified",
    "result_data": [
      {
        "name": "Username",
        "value": "AliceSmith"
      }
    ],
    "presentation_exchange_id": [
      "02ac589b-5463-4b0f-97a0-211221aaa54e"
    ],
    "error": "",
    "created_at": "2025-01-06T11:51:10.169Z",
    "updated_at": "2025-01-06T11:51:13.765Z"
  }
]

Verifications - Read Verification by ID

/api/v1/verifications/<verification_id> - GET

This endpoint allows you to retrieve an AnonCred verification request record by its ID.

Response Body Information:

Field name	Expected type/values	Examples	Notes
verification_id	integer	10	Primary identifier for the verification request record
connection_id	string	e2aed3c4-c0a1-4711-902e-f0a9eba618da	Identifier that ties the used connection to the verification request record
contact_id	string	contact123	Optional contact ID string used for processing the request record by known contact. Used with invitation_id, has first priority
invitation_id	integer	123	Optional integer used to process the request record by a connection tied to the invitation_id. Used with contact_id, has second priority
schema_id	string	null	Schema used for the verification request
schema_attributes	object	{...}	Contains the schema attributes and their restrictions, if any are provided
wallet_id	string	407e6215-17c5-4c81-901e-d75d9cc1a75a	Identifier that ties this record to an existing wallet
timeout	integer	10	Number of seconds the initial request waited for a completed request record
rule	string	“no rule”	Rules for the verification request
meta_data	object	null	Metadata for the verification request record
state	string	done	Current state of the verification
complete	boolean	true	This field does not indicate a verified presentation, only that the request record has finished its process.
result	boolean	true	Indicates a verified presentation. This field should be used alongside “complete” to determine a successful request record.
result_string	string	Verified	Custom string for helping to define the state of the request
result_data	array	[...]	Contains the verified attributes
presentation_exchange_id	array	[...]	Contains unique IDs for each proof request
error	string	“Public DID not set.”	Error message caught while processing the request record
created_at	timestamp	2025-01-06T11:51:10.169Z	Date/time this record was created
updated_at	timestamp	2025-01-06T11:51:10.169Z	Date/time this record was last updated

Sample Response Body:

{
    "verification_id": 1,
    "connection_id": "e2aed3c4-c0a1-4711-902e-f0a9eba618da",
    "contact_id": "",
    "invitation_id": 1,
    "schema_id": null,
    "schema_attributes": {
      "Username": {
        "restrictions": [
          {
            "schema_id": "Bo6yctq8hivGZWyaZcneJf:2:User:1.0"
          }
        ]
      }
    },
    "wallet_id": "407e6215-17c5-4c81-901e-d75d9cc1a75a",
    "timeout": 15,
    "rule": "no rule",
    "meta_data": null,
    "state": "done",
    "complete": true,
    "result": true,
    "result_string": "Verified",
    "result_data": [
      {
        "name": "Username",
        "value": "AliceSmith"
      }
    ],
    "presentation_exchange_id": [
      "02ac589b-5463-4b0f-97a0-211221aaa54e"
    ],
    "error": "",
    "created_at": "2025-01-06T11:51:10.169Z",
    "updated_at": "2025-01-06T11:51:13.765Z"
}

Verifications - Create Verification Request (JSON-LD)

/api/v1/verifications/json-ld - POST

This endpoint creates a Verification (JSON-LD) request record that handles verifying credentials for currently active connection(s) or future active connection(s) until the request record reaches a completed state.

Request Body Information:

Field name	Expected type/values	Examples	Notes
invitation_id	integer	123	Optional integer used to process the request record by a connection tied to the invitation_id. Used with contact_id, has second priority
contact_id	string	contact123	Optional contact ID string used for processing the request record by known contact. Used with invitation_id, has first priority
definitions	array	[{...}, {...}]	Definitions for the verification request. Contains context, attributes, and label
timeout	integer	10	Number of seconds the initial request will wait for a completed record before responding
rule	string	“no rule”	Rules for the verification request

Response Body Information:

The response body is an array of records. The following information is the data of each record:

Field name	Expected type/values	Examples	Notes
verification_id	integer	10	Primary identifier for the verification request record
connection_id	string	e2aed3c4-c0a1-4711-902e-f0a9eba618da	Identifier that ties the used connection to the verification request record
contact_id	string	contact123	Optional contact ID string used for processing the request record by known contact. Used with invitation_id, has first priority
invitation_id	integer	123	Optional integer used to process the request record by a connection tied to the invitation_id. Used with contact_id, has second priority
context	array	[“...”, “...”]	List of contexts used for this verification record
attributes	array	[...]	List of attributes to be verified
wallet_id	string	407e6215-17c5-4c81-901e-d75d9cc1a75a	Identifier that ties this record to an existing wallet
label	string	Email	Label for the verification request record
timeout	integer	10	Number of seconds the initial request waited for a completed request record
rule	string	“no rule”	Rules for the verification request
meta_data	object	null	Metadata for the verification request record
state	string	done	Current state of the verification request record
complete	boolean	true	This field does not indicate a verified request record, only that the request record has finished its process.
result	boolean	true	Indicates a verified request record. This field should be used alongside “complete” to determine a successful request record.
result_string	string	Verified	Custom string for helping to define the state of the request
result_data	array	[...]	Contains the verified attributes
presentation_exchange_id	array	[...]	Contains unique IDs for each proof request
error	string	“Controller Error! ….”	Error message caught while processing the request record
created_at	timestamp	2025-01-06T11:51:10.169Z	Date/time this record was created
updated_at	timestamp	2025-01-06T11:51:10.169Z	Date/time this record was last updated

Sample Response Body:

[
  {
    "verification_id": 1,
    "connection_id": "e2aed3c4-c0a1-4711-902e-f0a9eba618da",
    "contact_id": "",
    "invitation_id": 1,
    "context": [
      "https://www.w3.org/2018/credentials#VerifiableCredential",
      "https://www.w3.org/2018/credentials/v1",
      "https://purl.imsglobal.org/spec/vc/ob/vocab.html#OpenBadgeCredential"
    ],
    "attributes": [
      "id",
      "criteria"
    ],
    "wallet_id": "407e6215-17c5-4c81-901e-d75d9cc1a75a",
    "label": "your label here",
    "timeout": 15,
    "rule": "no rule",
    "meta_data": null,
    "state": "done",
    "complete": true,
    "result": false,
    "result_string": "Not Verified",
    "result_data": null,
    "presentation_exchange_id": [
      "52778677-a7be-4017-9b21-d146372f07e8"
    ],
    "error": "",
    "created_at": "2025-01-06T13:40:59.623Z",
    "updated_at": "2025-01-06T13:41:02.640Z"
  }
]

Verifications - Read Verifications By ID (JSON-LD)

/api/v1/verifications/json-ld/<verification_id> - GET

This endpoint fetches a JSON-LD verification request record by using its verification_id.

Response Body Information:

The response body is an array of records. The following information is the data of each record:

Field name	Expected type/values	Examples	Notes
verification_id	integer	10	Primary identifier for the verification request record
connection_id	string	e2aed3c4-c0a1-4711-902e-f0a9eba618da	Identifier that ties the used connection to the verification request record
contact_id	string	contact123	Optional contact ID string used for processing the request record by known contact. Used with invitation_id, has first priority
invitation_id	integer	123	Optional integer used to process the request record by a connection tied to the invitation_id. Used with contact_id, has second priority
context	array	[“...”, “...”]	List of contexts used for the verification record
attributes	array	[...]	List of attributes to be verified
wallet_id	string	407e6215-17c5-4c81-901e-d75d9cc1a75a	Identifier that ties this record to an existing wallet
label	string	Email	Label for the verification request record
timeout	integer	10	Number of seconds the initial request waited for a completed request record
rule	string	“no rule”	Rules for the verification request
meta_data	object	null	Metadata for the verification request record
state	string	done	Current state of the verification request record
complete	boolean	true	This field does not indicate a verified request record, only that the request record has finished its process.
result	boolean	true	Indicates a verified request record. This field should be used alongside “complete” to determine a successful request record.
result_string	string	Verified	Custom string for helping to define the state of the request
result_data	array	[...]	Contains the verified attributes
presentation_exchange_id	array	[...]	Contains unique IDs for each proof request
error	string	“Controller Error! ….”	Error message caught while processing the request record
created_at	timestamp	2025-01-06T11:51:10.169Z	Date/time this record was created
updated_at	timestamp	2025-01-06T11:51:10.169Z	Date/time this record was last updated

Sample Response Body:

{
  "verification_id": 1,
  "connection_id": "e2aed3c4-c0a1-4711-902e-f0a9eba618da",
  "contact_id": null,
  "invitation_id": 1,
  "context": [
    "https://www.w3.org/2018/credentials#VerifiableCredential",
    "https://www.w3.org/2018/credentials/v1",
    "https://purl.imsglobal.org/spec/vc/ob/vocab.html#OpenBadgeCredential"
  ],
  "attributes": [
    "id",
    "criteria"
  ],
  "wallet_id": "407e6215-17c5-4c81-901e-d75d9cc1a75a",
  "label": "your label here",
  "timeout": 15,
  "rule": "no rule",
  "meta_data": null,
  "state": "done",
  "complete": true,
  "result": false,
  "result_string": "Not Verified",
  "result_data": null,
  "presentation_exchange_id": [
    "52778677-a7be-4017-9b21-d146372f07e8"
  ],
  "error": "",
  "created_at": "2025-01-06T13:40:59.623Z",
  "updated_at": "2025-01-06T13:41:02.640Z"
}

Copyright 2025 Indicio PBC, All rights reserved