Introduction to acapy-cloud

Trust Ecosystem in a Box

Table of Contents

  1. First Step and Overview
  2. acapy-cloud Roles
  3. Workflows and Roles Overview
  4. Further Reading

First Steps

After spinning up the containers following the Quick Start Guide, you are ready to rumble.

Navigating to the Swagger UI endpoints:

provides a good overview of the intended functionalities. You'll find endpoints for admin actions (managing wallets) and tenant actions (for holders, issuers and verifiers). Additionally, there are trust registry and webhooks endpoints.

NOTE: Regardless of the multitude of containers and mechanisms running in acapy-cloud, its aforementioned Swagger UI's are the main interaction points intended between clients and the stack. These should be the only endpoints that clients should interact with.

Using the Swagger UI

The Swagger UI is documented. It shows you endpoints, expected parameters, and what example requests and responses look like. At the bottom of the UI, you can also find a list of all request/response models used, with definitions and example values.

Following Docker Container Logs

It can be handy to follow the logs of a specific container. A convenient way to do so is using:

kubectl logs -f $(kubectl get pods -l app.kubernetes.io/instance=YOUR_CONTAINER_NAME -o jsonpath="{.items[0].metadata.name}")

And replacing YOUR_CONTAINER_NAME with the name of the container you want to follow (e.g., endorser-web). You can find the container name in the docker-compose.yaml.

Authentication

Authentication is handled by acapy-cloud, and from a client perspective it's kept simple and convenient. Either, via the Swagger UI auth (padlock button in UI) or via the header data of your client specifying an x-api-key. Regardless of whether you use the UI or another client, the x-api-key value consists of two parts, separated by a dot:

{role}.{key/token}

This means the header has the format 'x-api-key: {role}.{key/token}, which would look like, e.g., 'x-api-key: governance.adminApiKey' or 'x-api-key: tenant.ey..' (JWT token).

The first part, role, specifies the role on the surface and targets the correct endpoints and authentication mechanisms under the hood. acapy-cloud knows how to interpret the roles and will produce the correct target URLs for the ACA-Py agent (tenant and tenant-admin target the multitenant agent, and governance targets the governance agent) with the correct headers expected by the agent.

For admin roles, pass the agent API key as the second part of {role}.{key}:

  • The governance role requires the Governance Agent API Key (which was used in starting up the governance agent) as the right-hand side token in the x-api-key header (in order to authenticate access to the governance agent).
  • The tenant-admin role requires the Multitenant Agent API Key (which was used in starting up the multitenant agent) as the right-hand side token in the x-api-key header (in order to target the admin interface of the multitenant agent).

Requests for the tenant role require the wallet JWT as the token in {role}.{token}. These requests will internally obtain a Bearer {TOKEN} header passed to the multitenant agent.

The definitions and capabilities of the three roles are as follows:

acapy-cloud Roles

Governance Role

Authentication header: 'x-api-key: governance.<GOVERNANCE AGENT API KEY>'

  • governance
    • is:
      • trust authority
      • transaction endorser
    • can:
      • make connections
      • create schemas
      • create credential definitions
      • manage trust registry
      • issue credential
      • verify credential
      • send basic messages

Tenant Administration Role

Authentication header: 'x-api-key: tenant-admin.<MULTITENANT AGENT API KEY>'

  • tenant-admin
    • is:
      • trust ecosystem admin
      • is transaction author
    • can:
      • only create, update, and delete tenants (wallets) for trust ecosystem issuers, verifiers, and users

Tenant Role (Trust Ecosystem Issuers, Verifiers, and Holders)

Authentication header: 'x-api-key: tenant.<TENANT JWT>'

  • tenant
    • is:
      • holder
      • issuer/verifier
    • if is issuer or verifier
      • issuers are transaction authors
      • verifiers are not transaction authors
      • automatically registered with the trust registry
      • can:
        • make connections
        • create credential definitions
        • issue credential
        • create/manage wallets
        • all transactions written to the ledger are counter-signed by the governance transaction endorser role
    • if is user (holder):
      • holder only
      • can:
        • make connections
        • manage own wallet
        • receive and store credentials
        • respond to/create proof request
        • send basic messages

Workflows and Roles Overview

Creating schemas

Using the admin role(s) you can create and register schemas. Successful schema creation will automatically write it to the ledger.

The ledger is also a useful place to look at what schemas you have at your disposal. In fact, this should be the preferred way, because schemas can exist on the ledger but have been invalidated on the trust registry. This will be checked by acapy-cloud and only valid schemas are allowed for use.

Credentials

The main feature revolves around issuing credentials, and verifying proofs based on these credentials.

Creating and issuing credentials

In order to issue a credential one must first:

  • Create a schema and
  • Register the schema with the trust registry.

via the governance agent. Only the governance agent can register a schema on the ledger.

Then:

  • Register an issuer with a tenant admin controller. This automatically registers them on the trust registry.

The registered issuer can then issue a credential, using the related schema on the trust registry, with the following steps:

  • Create a connection between the issuer and some other entity that you want to hold a credential
  • Once a connection is established, use the connection ID to create and issue a credential (have a look at the models in Swagger - it will tell you what data you need to provide and will receive back)
  • Holder accepts credential issuance
  • Holder stores credential in wallet

In summary, we have:

  • Created a schema (using the governance admin)
  • Registered a schema on the ledger (via the governance admin)
  • Created (a wallet for) an issuer and future holder using the tenant-admin
  • Registered an issuer (for a schema)
  • Created a connection between an issuer and a prospective holder (using connections API)
  • Proposed a credential to a prospective holder from an issuer
  • Accepted and stored an offered credential

Please note that when creating/issuing a credential, endorsing, and verifying credentials, acapy-cloud checks whether the requested instructions are valid against the trust registry.

Requesting a proof/using a credential

Now that we have an entity holding a credential (having a stored credential in their wallet), the next step is to use this credential. What we need to do:

  • Register a verifier on the trust registry (using a tenant-admin controller).
  • Establish a connection between a holder (of a credential) and a verifier (using connections/invitations API).
  • Using the data models and the 'dance' described in the ACA-Py docs, you can now arrange for negotiating a proof exchange

User management/Creating wallets

Using the admin role(s), you can create wallets for tenant or eco-system partners. These are all sub wallets. Successful creation returns the wallet creation response, including the wallet id and JWT for authentication.

Further Reading

Quick Start Guide

This guide will walk you through the steps to get acapy-cloud up and running smoothly.

Ensure that you meet the system requirements and have the necessary prerequisites installed.

System Requirements & Prerequisites

To successfully set up and run the project, your system should meet the following requirements and have the following prerequisites installed:

Requirements

  • Memory: 16GB of RAM
  • CPU: Intel i5 (minimum 4 cores) or equivalent
  • Disk Space: Approximately 32GB of free space for Docker images and data

Prerequisites

  • Operating System: Linux or macOS (Windows users should use WSL as outlined below)
  • Tools:
    • Bash
    • Docker
    • Docker Compose
    • Mise

[!NOTE] As of now, Mise does not support Windows. Windows users are recommended to use WSL. If using WSL, additional steps are required for Kind to work properly. Refer to the Kind WSL2 Guide for more details.

Installing Docker

Follow the official Docker installation instructions for your operating system:

Installing Docker Compose

Refer to the official Docker Compose installation guide:

Setting up Mise

Mise is used to install and manage development tooling for this project. Choose one of the following installation methods. We strongly recommend using your system's package manager to install Mise.

# Homebrew
brew install mise

# Build from source (requires Rust)
cargo install mise

# Arch Linux User Repository
yay -S mise-bin

# Debian/Ubuntu APT (amd64)
sudo apt-get update && sudo apt-get install -y gpg wget curl
sudo install -dm 755 /etc/apt/keyrings
wget -qO - https://mise.jdx.dev/gpg-key.pub | gpg --dearmor | sudo tee /etc/apt/keyrings/mise-archive-keyring.gpg > /dev/null
echo "deb [signed-by=/etc/apt/keyrings/mise-archive-keyring.gpg arch=amd64] https://mise.jdx.dev/deb stable main" | sudo tee /etc/apt/sources.list.d/mise.list
sudo apt-get update
sudo apt-get install -y mise

# Debian/Ubuntu APT (arm64)
sudo apt-get update && sudo apt-get install -y gpg wget curl
sudo install -dm 755 /etc/apt/keyrings
wget -qO - https://mise.jdx.dev/gpg-key.pub | gpg --dearmor | sudo tee /etc/apt/keyrings/mise-archive-keyring.gpg > /dev/null
echo "deb [signed-by=/etc/apt/keyrings/mise-archive-keyring.gpg arch=arm64] https://mise.jdx.dev/deb stable main" | sudo tee /etc/apt/sources.list.d/mise.list
sudo apt-get update
sudo apt-get install -y mise

For alternative installation methods, visit the Mise Installation Documentation.

Activating Mise in Your Shell

After installation, activate Mise by adding the following to your shell configuration:

# Bash
echo 'eval "$(mise activate bash)"' >> ~/.bashrc && source ~/.bashrc

# Zsh
echo 'eval "$(mise activate zsh)"' >> ~/.zshrc && source ~/.zshrc

# Fish
echo 'mise activate fish | source' >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish

Once activated, run the following commands to trust and install all required tools:

mise trust
mise install

For support with other shells, refer to the Mise Shell Support Documentation.

Project Setup

  1. Clone the Repository:

    git clone https://github.com/didx-xyz/acapy-cloud
cd acapy-cloud

  2. Start the Project:

    In the root directory of the project, execute:

    mise run tilt:up

  3. Stop the Project:

    When you're done, stop the project by running:

    mise run tilt:down

  4. Destroy the Kind Cluster:

    To remove the Kind cluster as well:

    mise run tilt:down:destroy

  5. Clean Slate (Optional):

    To remove everything, including the Docker cache, execute:

    mise run tilt:down:destroy:all

Accessing Services

Once the project is running, access various services via their Swagger interfaces at the following URLs:

Customization

Customize each Docker container's environment parameters by editing its corresponding .yaml file located within the helm/acapy-cloud/conf/local directory. For example, to change the auto-provision setting for the ACA-Py multitenant instance from true to false, modify the ACAPY_AUTO_PROVISION value under the env section in helm/acapy-cloud/conf/local/multitenant-agent.yaml. To configure log levels, search for LOG_LEVEL and set to your desired level.

Next Steps

  • Common Steps: Understand the general capabilities of the project once it's up and running.
  • Example Flows: Learn how to perform specific SSI flows.

Trust Registry

As a client, you can retrieve the trust registry but not alter it. This design is intentional as only administrative actions should modify the trust registry, and such actions are only possible with an admin role.

NOTE: The Trust Registry GET API endpoint is not protected and should not be publicly accessible.

The Trust Registry serves as a gatekeeper interface for interactions, maintaining the truth states about actors, their respective roles as issuers and/or verifiers, and schemas.

The Swagger docs are divided into three main sections:

  • Actor - For actor information and actions on the ledger
  • Schema - For schema information and actions on the ledger
  • Default - To retrieve all information from the registry

The trust registry provides access to this data via actors and schemas keys, which can be found in the JSON blob retrieved from requesting the endpoint. Their structures are as follows:

{
    "actors": [
    {
      "name": "Test Actor-0.26703024264670694",
      "roles": [
        "issuer",
        "verifier"
      ],
      "did": "did:sov:XfbLjZFxgoznN24LUVxaQH",
      "id": "test-actor-0.26703024264670694",
      "didcomm_invitation": null,
      "image_url": "https://upload.wikimedia.org/wikipedia/commons/7/70/Example.png"
    },
    ...
}

The fields here should be self-explanatory.

And,

{
    "schemas": [
        "z5Bug71M7Sj7cYpbVBDmN:2:test_schema:0.3",
        "MnspmfkzjLXd6WXyjCYJKW:2:test_schema:0.3",
        "E2HWvrZYs9SCXXHCZtFV1U:2:test_schema:0.3",
        ...
    ]
}

where "z5Bug71M7Sj7cYpbVBDmN:2:test_schema:0.3" represents the schema ID, name, and version respectively.

NOTE: In a production environment, this should not be exposed to the internet or interacted with directly. It's advisable to either avoid exposing this to the internet or set up a separate security layer for the trust registry. This is because it's crucial to prevent unauthorized individuals from making changes to the trust registry.

Trust Registry Interactions

Below, we outline where and how the Trust Registry is consulted to verify that Issuers, Verifiers, and Schemas are compliant.

Issuer Actions

When a user/tenant initiates any issuer-related action, the Trust Registry is used to verify the following:

  1. Issuer Verification:
    • For creating credential definitions, creating credential offers, and issuing credentials: Confirms that the tenant is registered with the role of an issuer.
    • For accepting credentials: Confirms that the tenant is receiving a credential from a registered issuer.
  2. Schema Validation: Ensures that the referenced schema is valid and registered within the Trust Registry.

If either step fails, the operation is blocked, and an appropriate error message is returned to the user. The operation is logged and able to be reviewed by an administrator.

---
title: Trust Registry called during issuer operations
---
flowchart LR
    App(Issuer Action:<br>Credential Operations) -->|Consults| TR[Trust Registry]
    subgraph Trust Registry Checks
      TR -->|Validates| Check1{Issuer Verification}
      Check1 -->|If Unauthorized| Block[⨯ Block Operation]
      Check1 -->|If Authorized| Check2{Schema Validation}
      Check2 -->|Not on TR| Block
    end
    Check2 -->|If Registered| Continue[✓ Proceed with Operation]

    style TR fill:#a8d1ff,stroke:#1e88e5,color:black
    style Block fill:#ffcdd2,stroke:#e53935,color:black
    style Continue fill:#c8e6c9,stroke:#43a047,color:black

Verifier Actions

When a tenant initiates any verifier-related action (sending proof requests or receiving proof presentations), the Trust Registry is used to verify the following:

  1. Verifier Verification:
    • For sending proof requests: Confirms that the tenant sending the request is registered as a verifier.
    • For accepting proof requests: Validates that the proof is being presented to a registered verifier.
  2. Schema Validation: Ensures that the attributes being requested are associated with schemas registered within the Trust Registry.

If either step fails, the operation is blocked as a bad request, with an appropriate error message returned to the user.

---
title: Trust Registry called during proof requests
---
flowchart LR
  Start(Verifier Action:<br>Proof Request Operations) -->|Consult| TR[Trust Registry]
  subgraph Trust Registry Checks
    TR -->|Validates| Check1{Verifier Verification}
    Check1 -->|If Unauthorized| Block[⨯ Block Operation]
    Check1 -->|If Authorized| Check2{Schema exists on TR}
    Check2 -->|Not on TR| Block
  end
  Check2 -->|If Registered| Continue[✓ Proceed with Operation]

  style TR fill:#a8d1ff,stroke:#1e88e5,color:black
  style Block fill:#ffcdd2,stroke:#e53935,color:black
  style Continue fill:#c8e6c9,stroke:#43a047,color:black

Webhooks/Event Consumption

Primary Method: NATS

The recommended and most efficient way to consume events is through our NATS implementation. NATS provides a robust, scalable solution for event streaming and processing. For detailed information about consuming events from our NATS implementation, please refer to this document: NATS.

Alternative: Waypoint Service

The Waypoint service provides a specialized Server-Sent Events (SSE) endpoint for cases where you need to wait for a specific event that you know is coming. This is particularly useful when you need to track the state change of a specific entity and have all the necessary filter information.

The Waypoint service exposes a single SSE endpoint, via the main app, for event streaming:

  • GET /v1/sse/{wallet_id}/{topic}/{field}/{field_id}/{desired_state}

This endpoint is designed for targeted event retrieval where you can specify exact filters to wait for a particular event.

How to use

The endpoint requires specific filter parameters:

  • wallet_id: Identifier for the specific wallet
  • topic: The event topic to subscribe to
  • field: Filter field from the event payload
  • field_id: Specific value for the filter field
  • desired_state: The desired state of the event

For example, if you're waiting for a specific connection to reach the 'completed' state, you would use:

  • field: "connection_id"
  • field_id: "<your_connection_id>"
  • desired_state: "completed"

The stream will remain open until the desired event (matching the filters) is found and returned, at which point the stream will be closed or timeout after 60 seconds.

Valid topics include:

topics = Literal[
    "basic-messages",
    "connections",
    "credentials",
    "credentials_indy",
    "credentials_ld",
    "endorsements",
    "issuer_cred_rev",
    "oob",
    "problem_report",
    "proofs",
    "revocation",
]

Implementing Your Event Listener

Here's an example of how to implement a SSE event listener using JavaScript:

const EventSource = require('eventsource');

const wallet_id = '<your_wallet_id>';
const url = `http://cloudapi.127.0.0.1.nip.io/tenant-admin/v1/sse/${wallet_id}/proofs/connections/<some_id>/done`;

const headers = {
  'x-api-key': 'tenant.<tenant/wallet_token>',
};

const eventSource = new EventSource(url, { headers });

// Event listener for incoming server-sent events
eventSource.onmessage = (event) => {
  const eventData = JSON.parse(event.data);
  console.log("EVENT ==> ", eventData);
};

// Event listener for handling errors
eventSource.onerror = (error) => {
  console.error('EventSource error:', error);
  // Add your error handling logic here
};

console.log("Listening for events...");

This script establishes a connection to the SSE endpoint and listens for incoming events. When an event is received, it's logged to the console. Error handling is also implemented to manage any issues that may arise during the connection.

NOTE: Ensure that you replace <your_wallet_id> with the actual wallet ID and use the appropriate x-api-key for authentication.

Authentication

The Waypoint service requires authentication to access the SSE endpoint. This is managed through the x-api-key header in the request. The key should be in the format tenant.<tenant/wallet_token>. Failing to provide valid authentication will result in a 403 HTTP Error.

A tenant will only be able to listen to events that belong to their wallet and a tenant-admin is able to listen to all events belonging to their group.

NATS

NATS is an open-source messaging system designed for high-performance, lightweight, and reliable communication between distributed applications. It supports pub-sub (publish-subscribe), request-reply, and message queue patterns, allowing for flexible communication between microservices, IoT devices, and cloud-native systems.

Key Features

  • Simple: Text-based protocol with straightforward publish-subscribe semantics
  • Fast: Written in Go, capable of millions of messages per second
  • Lightweight: Small footprint, minimal dependencies
  • Cloud Native: Built for modern distributed systems

Core Concepts

  • Publishers: Send messages to subjects
  • Subscribers: Receive messages from subjects
  • Subjects: Named channels for message routing
  • Queue Groups: Load balance messages across subscribers

Message Patterns

  • Publish/Subscribe: One-to-many message distribution
  • Request/Reply: Synchronous communication
  • Queue Groups: Load balanced message processing
  • Stream Processing: Persistent message streams (via NATS Streaming/JetStream)

Consuming our NATS

Please contact us for help with connecting/authenticating to our NATS service

Governance as Code: Building Your Trust Ecosystem

This guide introduces key concepts and demonstrates how to programmatically define and manage your trust ecosystem using acapy-cloud's APIs. You'll learn how to:

  • Define schemas for credentials
  • Create and manage different types of tenants (issuers, verifiers, holders)
  • Create credential definitions
  • Query and manage the trust registry

The examples use the provided Swagger UI interfaces but can also be automated through direct API calls.

1. Schemas

Schemas are used to define attributes related to credentials. To define schemas for your trust ecosystem, follow the steps below:

  1. Access the API through the Governance interface.
  2. Authenticate with governance. + APIKEY role.
  3. Generate a new schema with a POST to the following API endpoint: /v1/definitions/schemas.

An example of a successful response to generate a DID:

{
  "id": "PWmeoVrsLE2pu1idEwWFRW:2:test_schema:0.3.0",
  "name": "test_schema",
  "version": "0.3.0",
  "attribute_names": ["speed"]
}

2. Creating Tenants

In the multi-tenant environment, you can set up issuers, verifiers, and holders. Each tenant gets their own wallet, and the different roles have different privileges.

Issuers

To create an issuer tenant for your trust ecosystem, follow the steps below:

  1. Access the API through the Multitenant-Admin.
  2. Authenticate with tenant-admin. + APIKEY role.
  3. Create a new tenant with a POST to the following API endpoint: /tenant-admin/v1/admin/tenants/, using the example request body below.
{
  "wallet_label": "Demo Issuer",
  "wallet_name": "Faber",
  "roles": ["issuer"],
  "group_id": "API demo",
  "image_url": "https://upload.wikimedia.org/wikipedia/commons/7/70/Example.png"
}

An example of a successful response to create a new Issuer Tenant:

{
  "access_token": "tenant.eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ3YWxsZXRfaWQiOiIwNTYxODM2Mi1iMDI0LTQ2YzUtYjgzYy02YzZiOGM3NzkyZDgiLCJpYXQiOjE3MDAxMjgxNTN9.x_0xa9glFFW44PbfoBiEQY0Lt0dOBLVJgUkdavgusWU",
  "wallet_id": "05618362-b024-46c5-b83c-6c6b8c7792d8",
  "wallet_label": "Demo Issuer",
  "wallet_name": "Faber",
  "created_at": "2025-01-16T09:49:13.067595Z",
  "updated_at": "2025-01-16T09:49:13.111843Z",
  "image_url": "https://upload.wikimedia.org/wikipedia/commons/7/70/Example.png",
  "group_id": "API demo"
}

Verifiers

To create a verifier, follow these steps:

  1. Access the API through Multitenant-Admin

  2. Authenticate using the tenant-admin.+APIKEY role

  3. Generate a new tenant with a POST request to the API endpoint /tenant-admin/v1/admin/tenants/ using the request body detailed in the example below

    {
 "wallet_label": "Demo Verifier",
 "wallet_name": "Acme",
 "roles": [
  "verifier"
 ],
 "group_id": "API demo",
 "image_url": "https://upload.wikimedia.org/wikipedia/commons/7/70/Example.png"
}'

  4. Below is an example of a successful response to the creation of a new Verifier Tenant:

    {
  "access_token": "tenant.eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ3YWxsZXRfaWQiOiIwNTYxODM2Mi1iMDI0LTQ2YzUtYjgzYy02YzZiOGM3NzkyZDgiLCJpYXQiOjE3MDAxMjgxNTN9.x_0xa9glFFW44PbfoBiEQY0Lt0dOBLVJgUkdavgusWU",
  "wallet_id": "05618362-b024-46c5-b83c-6c6b8c7792d8",
  "wallet_label": "Demo Verifier",
  "wallet_name": "Acme",
  "created_at": "2025-01-16T09:49:13.067595Z",
  "updated_at": "2025-01-16T09:49:13.111843Z",
  "image_url": "https://upload.wikimedia.org/wikipedia/commons/7/70/Example.png",
  "group_id": "API demo"
}

Holders

Holders are regular tenants without any additional privileges in the Trust Ecosystem. They are created in the same way, without any roles in the create request

  1. Access the API through Multitenant-Admin

  2. Authenticate using tenant-admin.+APIKEY role

  3. Generate a new tenant with a POST to the API endpoint /tenant-admin/v1/admin/tenants/ using the request body in the example below

    {
  "wallet_label": "Demo Holder",
  "wallet_name": "Alice",
  "group_id": "API demo",
  "image_url": "https://upload.wikimedia.org/wikipedia/commons/7/70/Example.png"
}

  4. Here is an example of a successful response to creating a new Holder Tenant:

    {
  "access_token": "tenant.eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ3YWxsZXRfaWQiOiI0ZTBjNzBmYi1mMmFkLTRmNTktODFmMy05M2Q4ZGY5Yjk3N2EiLCJpYXQiOjE3MDAxMTkzMjJ9.lXrNVWN_bzRXkkBfOd1Yey6D0iqsHpOuXt6aZYwMLp4",
  "wallet_id": "4e0c70fb-f2ad-4f59-81f3-93d8df9b977a",
  "wallet_label": "Demo Holder",
  "wallet_name": "Alice",
  "created_at": "2025-01-16T07:22:02.086605Z",
  "updated_at": "2025-01-16T07:22:02.105980Z",
  "image_url": "https://upload.wikimedia.org/wikipedia/commons/7/70/Example.png",
  "group_id": "API demo"
}

3. Credential Definitions

Credential definitions are expected to be created by all Issuers within the trust ecosystem who wish to issue credentials to holders. The Trust Authority, which administers the trust ecosystem and enables tenants to write to the Indy Ledger, acts as the Transaction Endorser of the Trust Ecosystem. Meanwhile, Issuers serve as Transaction Authors within the Trust Ecosystem. For additional information on Transaction Endorsers and Transaction Authors, please refer to Aries Transaction Endorser Support.

To create credential definitions through the Transaction Endorser Protocol for trust ecosystem issuers, follow the steps below:

  1. Access the Tenant Swagger UI

  2. Authenticate as an Issuer using tenant.+JWTKey x-api-key

  3. Create a new schema with a POST to the API endpoint /v1/definitions/credentials using the request body illustrated in the example below.

    NOTE: The schema ID should already exist in the ledger and be accessible in the Trust Registry

    {
  "tag": "default",
  "schema_id": "JPqFhPEM4UiR2ZNK9CM4NA:2:test_schema:0.3.0"
}

  4. Below is an example of a successful response to writing a credential definition:

    {
  "id": "EfFA6wi7fcZNWzRuHeQqaj:3:CL:8:default",
  "tag": "default",
  "schema_id": "JPqFhPEM4UiR2ZNK9CM4NA:2:test_schema:0.3.0"
}

4. Trust Registry

To query entries in the Trust Registry, adhere to the following steps:

  1. Access the Public Swagger UI

  2. Authenticate as an Issuer using tenant.+JWTKey role

    NOTE: The Trust Registry is currently public and accessible to anyone on the internet

  3. The trust-registry has 5 GET endpoints:

    • GET /v1/trust-registry/schemas will return all schemas on the trust registry

      Response:

    [
  {
    "did": "GXK1Ubc58DvZDe48zPYdcf",
    "name": "Proof of Person",
    "version": "0.1.0",
    "id": "GXK1Ubc58DvZDe48zPYdcf:2:Proof of Person:0.1.0"
  },
  {
    "did": "GXK1Ubc58DvZDe48zPYdcf",
    "name": "Proof of Address",
    "version": "0.1.0",
    "id": "GXK1Ubc58DvZDe48zPYdcf:2:Proof of Address:0.1.0"
  },
  {
    "did": "GXK1Ubc58DvZDe48zPYdcf",
    "name": "Proof of Medical Aid",
    "version": "0.1.0",
    "id": "GXK1Ubc58DvZDe48zPYdcf:2:Proof of Medical Aid:0.1.0"
  },
  {
    "did": "GXK1Ubc58DvZDe48zPYdcf",
    "name": "Proof of Bank Account",
    "version": "0.1.0",
    "id": "GXK1Ubc58DvZDe48zPYdcf:2:Proof of Bank Account:0.1.0"
  }
]

    • GET /v1/trust-registry/schemas/{schema_id} will return the schema based on id passed

      Response:

    {
  "did": "GXK1Ubc58DvZDe48zPYdcf",
  "name": "Proof of Bank Account",
  "version": "0.1.0",
  "id": "GXK1Ubc58DvZDe48zPYdcf:2:Proof of Bank Account:0.1.0"
}

    • GET /v1/trust-registry/actors will return all actors on the trust registry

    • Optionally one of the following query parameters can be passed to get a specific actor:

      • actor_did
      • actor_id
      • actor_name

      Response:

    [
  {
    "id": "9bdbc626-1499-48e2-a5db-878d347e290b",
    "name": "[email protected]",
    "roles": ["issuer"],
    "did": "did:sov:J1Sg8UHXyuyBCUUpRY3EeZ",
    "didcomm_invitation": "http://cloudapi.127.0.0.1.nip.io/tenant-admin?oob=eyJAdHlwZSI6ICJodHRwczovL2RpZGNvbW0ub3JnL291dC1...Y29tbS5vcmcvZGlkZXhjaGFuZ2UvMS4wIl19"
  },
  {
    "id": "fe523496-e0b5-4aea-a038-6ed6cbd686b8",
    "name": "[email protected]",
    "roles": ["verifier"],
    "did": "did:key:z6MkkUK3zRys1WezsaoAtXZtAJrhP7dh5qxbpJMe6cbDcW3s",
    "didcomm_invitation": "http://cloudapi.127.0.0.1.nip.io/tenant-admin?oob=eyJAdHlwZSI6ICJodHRwczovL2RpZGNvbW0ub3JnL291dC1vZi1iYW...jb21tLm9yZy9kaWRleGNoYW5nZS8xLjAiXX0="
  },
  {
    "id": "cf058a03-1f88-4fa9-97dc-96a9cabf8d3e",
    "name": "Bank Issuer & Verifier",
    "roles": ["issuer", "verifier"],
    "did": "did:sov:UhJ5C8hgSiNzpoAYwVcnW9",
    "didcomm_invitation": "http://cloudapi.127.0.0.1.nip.io/tenant-admin?oob=eyJAdHlwZSI6ICJodHRwczovL2RpZGNvbW0ub3Jn...odHRovL2RpZGNvbW0ub3JnL2RpZGV4Y2hhbmdlLzEuMCJdfQ=="
  }
]
    • GET /v1/trust-registry/actors/issuers will return all actors with issuer as a role
    • GET /v1/trust-registry/actors/verifiers will return all actors with verifier as a role

For how to establish connections, issue credentials, and verify proofs, please refer to the Example Flows guide.

Example Flow

This document will provide you with more detail through the end-to-end flows:

  1. Onboarding an Issuer, Verifier and a Holder
  2. Creating a Credential Schema
  3. The Issuer creating a Credential definition
  4. Create Connection between Issuer and Holder
  5. Issuing a credential to a Holder
  6. Create Connection between Verifier and Holder
  7. The Verifier doing a proof request against the Holder's Credential
  8. Revoking Credentials
  9. Verifying Revoked Credentials
  10. Self-Attested Attributes
  11. Restrictions on Proofs
  12. Requested Predicates

1: Onboarding Tenants

When onboarding users, also referred to as tenants or wallets, you need to use the tenant-admin role. Below, you will find the curl commands used to create an Issuer, Verifier and a Holder. If you are using the Multitenant-Admin Swagger UI to do the onboarding, just use the JSON in the field marked with -d in the curl commands.

The difference between an Issuer, Verifier and Holder is that issuers and verifiers have privileged roles, and are therefore written to the trust registry, allowing them to issue credentials and to verify proof requests in our ecosystem. A holder is a regular tenant without a role, and therefore cannot act as an issuer or verifier. They are all "tenants", and therefore each will have a tenant access token.

Onboard Issuer

Note the x-api-key used during the tenant creation that follows

curl -X 'POST' \
  'http://cloudapi.127.0.0.1.nip.io/tenant-admin/v1/admin/tenants' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: tenant-admin.adminApiKey' \
  -d '{
  "wallet_label": "Demo Issuer",
  "wallet_name": "Faber",
  "roles": [
    "issuer"
  ],
  "group_id": "API demo",
  "image_url": "https://upload.wikimedia.org/wikipedia/commons/7/70/Example.png"
}'

Response:

{
  "access_token": "tenant.eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ3YWxsZXRfaWQiOiJkZWEwYTlmYi0wODhkLTQ2ODktYmM5Yy04YTFiYWI5MDYxNzAiLCJpYXQiOjE3MDA2MzE4NzN9.7Pwb5Q6BKHA6N9luJH1uDiHdgSZXPWwvdV4O0xZeqFQ",
  "wallet_label": "Demo Issuer",
  "wallet_name": "Faber",
  "created_at": "2025-01-20T09:49:45.809544Z",
  "updated_at": "2025-01-20T09:49:45.841851Z",
  "image_url": "https://upload.wikimedia.org/wikipedia/commons/7/70/Example.png",
  "group_id": "API demo"
}

The access_token is what must be used as x-api-key to act as this tenant.

Onboard Verifier

curl -X 'POST' \
  'http://cloudapi.127.0.0.1.nip.io/tenant-admin/v1/admin/tenants' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: tenant-admin.adminApiKey' \
  -d '{
  "wallet_label": "Demo Verifier",
  "wallet_name": "Acme",
  "roles": [
    "verifier"
  ],
  "group_id": "API demo",
  "image_url": "https://upload.wikimedia.org/wikipedia/commons/7/70/Example.png"
}'

Response:

{
  "access_token": "tenant.eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ3YWxsZXRfaWQiOiI5Mjg5MzY1OC1mZTJkLTRmMmQtODI2OC1hNjBhNjAxOTQ1YTkiLCJpYXQiOjE3MDA2MzE2MTd9.E5USXOEmKlpZelGzwGs7VxZWfQzvOBPADB2r95pyuWA",
  "wallet_id": "92893658-fe2d-4f2d-8268-a60a601945a9",
  "wallet_label": "Demo Verifier",
  "wallet_name": "Acme",
  "created_at": "2025-01-22T05:40:16.606565Z",
  "updated_at": "2025-01-22T05:40:16.630619Z",
  "image_url": "https://upload.wikimedia.org/wikipedia/commons/7/70/Example.png",
  "group_id": "API demo"
}

Onboard Holder

curl -X 'POST' \
  'http://cloudapi.127.0.0.1.nip.io/tenant-admin/v1/admin/tenants' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: tenant-admin.adminApiKey' \
  -d '{
  "wallet_label": "Demo Holder",
  "wallet_name": "Alice",
  "group_id": "API demo",
  "image_url": "https://upload.wikimedia.org/wikipedia/commons/7/70/Example.png"
}'

Response:

{
  "access_token": "tenant.eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ3YWxsZXRfaWQiOiIyMjcxZjdmMi03MzU5LTRkMDgtYWI2Ni0xMWI2NjFlZDA5ZjQiLCJpYXQiOjE3MDA2MzE2OTN9.uKfcvq06KSlLHlGkH9zaXHcFA3V2WzNvxRVbyNgjXNc",
  "wallet_id": "2271f7f2-7359-4d08-ab66-11b661ed09f4",
  "wallet_label": "Demo Holder",
  "wallet_name": "Alice",
  "created_at": "2025-01-22T05:41:32.662976Z",
  "updated_at": "2025-01-22T05:41:32.707778Z",
  "image_url": "https://upload.wikimedia.org/wikipedia/commons/7/70/Example.png",
  "group_id": "API demo"
}

Next: Create Credential Schema

2: Create Schema

Only the Governance role can create Schemas. Note the x-api-key used in the following request.

curl -X 'POST' \
  'http://cloudapi.127.0.0.1.nip.io/governance/v1/definitions/schemas' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: governance.adminApiKey' \
  -d '{
  "name": "Person",
  "version": "0.1.0",
  "attribute_names": [
    "Name","Surname","Age"
  ]
}'

Response:

{
  "id": "QpSW24YVf61A3sAWxArfF6:2:Person:0.1.0",
  "name": "Person",
  "version": "0.1.0",
  "attribute_names": ["Surname", "Age", "Name"]
}

Note down the schema id in the id field.

Next: Create Credential Definition

3: Create Credential Definition

Once a schema has been created by the governance agent, the Issuer can create a credential definition. They will use the credential definition as a unique reference to the schema.

Creating a Credential Definition

To create a credential definition, the issuer needs to send a POST request to the appropriate endpoint. Below is an example of how to create a non-revocable credential definition:

curl -X 'POST' \
  'http://cloudapi.127.0.0.1.nip.io/tenant/v1/definitions/credentials' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: tenant.<Issuer token>' \
  -d '{
  "tag": "Demo Person",
  "schema_id": "QpSW24YVf61A3sAWxArfF6:2:Person:0.1.0",
  "support_revocation": false
}'

Response:

{
  "id": "2hPti9M3aQqsRCy8N6jrDB:3:CL:10:Demo Person",
  "tag": "Demo Person",
  "schema_id": "QpSW24YVf61A3sAWxArfF6:2:Person:0.1.0"
}

Note down the credential definition id in the id field.

If you don't need revocation support, you can continue to the next section: Create Connection. Otherwise, stick around for an explanation of revocable credential definitions.

Creating a Revocable Credential Definition

Revocation enables an issuer to revoke credentials, i.e., make a credential invalid some time after issuance. The process to make credentials revocable is straightforward, but there are a few things the issuer should keep track of. The goal of this section is to explain everything involved in revocation.

To issue credentials that are revocable, the credential definition needs to be created with revocation support enabled. When creating a credential definition, set "support_revocation": true. This will enable revocation on all credentials issued against this credential definition.

Example payload for creating a revocable credential definition:

{
  "tag": "My cred def",
  "schema_id": "QpSW24YVf61A3sAWxArfF6:2:Person:0.1.0",
  "support_revocation": true
}

The creation of a credential definition with revocation enabled can take up to a minute before a user gets a response from the API endpoint. The reason for this is the creation of revocation registries. These registries are essential for the cryptographic processes involved with revocation. See more on this here.

The management of these registries is obfuscated away from the user as it can be complicated and cumbersome. However, there are a few things to take note of. Once a registry is full, the application will automatically switch to a new registry. These registries are created on the fly, and the application will always have two "active" registries: one that is currently being used and the next one in the queue, i.e., the one the application will switch to once the current one is filled.

There is also a fee associated with the creation of these registries as there is a definition of them that needs to end up on the ledger. These definitions are needed for the revocation process to work.

There is an event associated with the creation of these revocation registries with the topic name revocation. Here is an example event of an initial event associated with the creation of the revocation registries:

{
  "wallet_id": "8960ee4d-d79d-4444-abca-ad2edbfef600",
  "topic": "revocation",
  "origin": "tenant faber",
  "group_id": "GroupA",
  "payload": {
    "created_at": "2025-01-02T08:11:11.039583Z",
    "cred_def_id": "WWzcvsHULP1Fkf9GUYRZg8:3:CL:8:Epic",
    "error_msg": null,
    "issuer_did": "WWzcvsHULP1Fkf9GUYRZg8",
    "max_cred_num": 4,
    "pending_pub": [],
    "record_id": "bf1219ca-75bf-4931-911b-1fe2ace39683",
    "revoc_def_type": "CL_ACCUM",
    "revoc_reg_def": null,
    "revoc_reg_entry": null,
    "revoc_reg_id": "WWzcvsHULP1Fkf9GUYRZg8:4:WWzcvsHULP1Fkf9GUYRZg8:3:CL:8:Epic:CL_ACCUM:bf1219ca-75bf-4931-911b-1fe2ace39683",
    "state": "init",
    "tag": null,
    "tails_hash": null,
    "tails_local_path": null,
    "tails_public_uri": null,
    "updated_at": "2025-01-02T08:11:11.039583Z"
  }
}

Note: This event only fires on the creation of registries or when registries fill up and a new one takes its place. This event does not fire with the revocation of credentials.

When a credential is issued with revocation support, it will be intrinsically connected with a registry.

Next: Create Connection

4: Create Connection

Now that the Issuer has a credential definition, they can start issuing credentials. However, in order to do that, they first need to create a connection to the holder. There are multiple ways to create connections. We will use the /v1/connections/ endpoints in these examples.

Create connection between Holder and Issuer

POST /v1/connections/did-exchange/create-request

This endpoint allows a tenant to send a request to another tenant with a public DID to create a connection. Tenants on the platform are configured to auto-accept connections; therefore, connections will proceed to completion automatically.

The following parameters are available on the endpoint:

  • their_public_did The DID of the party you want to connect to.
  • alias An alias for the connection. Defaults to None.
  • goal Optional self-attested string for sharing the intent of the connection.
  • goal_code Similar to goal.
  • my_label Will be the wallet label, can be overwritten.
  • use_did Your local DID to use for the connection.
  • use_did_method The method to use for the connection: "did:peer:2" or "did:peer:4".
  • use_public_did Use your public DID for this connection. Defaults to False.

Note: Only one of use_did, use_did_method or use_public_did should be specified. If none of these are specified, a new local DID will be created for this connection.

As the Holder, we create a connection with the Issuer using the did-exchange protocol.

Response:

{
  "alias": "Alice-Faber",
  "connection_id": "165148b3-7e3b-4dec-9568-69694a2ba67f",
  "connection_protocol": "didexchange/1.0",
  "created_at": "2025-01-14T09:31:52.686641Z",
  "error_msg": null,
  "invitation_key": null,
  "invitation_mode": "once",
  "invitation_msg_id": null,
  "my_did": "EYPGsWQrpZbxSEbcHRUZum",
  "state": "request-sent",
  "their_did": "did:sov:VvWbYuE8GAkxCgKp6FnPWK",
  "their_label": null,
  "their_public_did": "did:sov:VvWbYuE8GAkxCgKp6FnPWK",
  "their_role": "inviter",
  "updated_at": "2025-01-14T09:31:52.724460Z"
}

Both tenants can listen to Webhooks to track the progress of the connection being made. Once the state is completed, the connection is established. This can also be verified by fetching connection records for the holder or issuer, and validating that their connection has transitioned to state: completed.

Below is an example of a webhook event indicating the completed state.

Note: The field IDs will be unique to each tenant, i.e., the connection_id of the Issuer will be different from that of the Holder, even though they refer to the same connection.

{
  "wallet_id": "4e0c70fb-f2ad-4f59-81f3-93d8df9b977a",
  "topic": "connections",
  "origin": "multitenant",
  "payload": {
    "alias": "Holder <> Issuer",
    "connection_id": "359b30a2-c98d-4c00-b318-8185d1d0e64d",
    "connection_protocol": "didexchange/1.0",
    "created_at": "2025-01-16T07:57:18.451554Z",
    "error_msg": null,
    "invitation_key": "8Vd5YSVBw5p6BJ8nHngZ2UcCKBmTSxQHoNWfaBQJXW5U",
    "invitation_mode": "once",
    "invitation_msg_id": "0ef82415-20ba-4d1e-818b-92a70355ec6e",
    "my_did": "NXk4JkDpFff4MpnTwvn1Wa",
    "state": "completed",
    "their_did": "LN2WMyrMFH74L1GTkSteka",
    "their_label": "Demo Issuer",
    "their_public_did": null,
    "their_role": "inviter",
    "updated_at": "2025-01-16T07:57:18.748560Z"
  }
}

Next: 5: Issue a Credential

5: Issuing a Credential

Now the Issuer issues credentials

Now that a connection has been made between the Issuer and the Holder, the Issuer can send the credential to the Holder using the connection_id from the Issuer's perspective.

Again both tenants can listen for events on the topic: credentials

Issuing a Non-Revocable Credential

To issue a non-revocable credential, the issuer needs to send a POST request to the appropriate endpoint. Below is an example of how to issue a non-revocable credential:

curl -X 'POST' \
  'http://cloudapi.127.0.0.1.nip.io/tenant/v1/issuer/credentials' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: tenant.<Issuer token>' \
  -d '{
  "type": "indy",
  "indy_credential_detail": {
    "credential_definition_id": "QrHj82kaE61jnB5451zvvG:3:CL:12:Demo Person",
    "attributes": {
      "Name": "Alice",
      "Surname": "Holder",
      "Age": "25"
    }
  },
  "connection_id": "c78f9423-370e-4800-a48e-962456083943"
}'

Response:

{
  "attributes": {
    "Name": "Alice",
    "Surname": "Holder",
    "Age": "25"
  },
  "connection_id": "c78f9423-370e-4800-a48e-962456083943",
  "created_at": "2025-01-20T09:59:29.820002Z",
  "credential_definition_id": "QrHj82kaE61jnB5451zvvG:3:CL:12:Demo Person",
  "credential_exchange_id": "v2-f126edb7-1ac1-43a3-bf1f-60b8feae4701",
  "did": null,
  "error_msg": null,
  "role": "issuer",
  "schema_id": "FS9J6WZ6KVxwy5eGH32CgM:2:Person:0.1.0",
  "state": "offer-sent",
  "thread_id": "9ceeb941-4ebd-42ec-9ffc-ea0b7fe39722",
  "type": "indy",
  "updated_at": "2025-01-20T09:59:29.820002Z"
}

As you can see from the state, an offer has now been sent, and needs to be accepted/requested by the holder.

Note that the issuer will now have what's called a credential exchange record in state: offer-sent. Pending exchange records can be viewed by calling GET /v1/issuer/credentials, and completed credential exchange records are deleted by default, but can be preserved by adding an optional save_exchange_record=True field to the request.

Issuing a Revocable Credential

Credentials that support revocation are issued in the same way as described above, but there is additional information that the issuer needs to keep track of.

There is a webhook event topic that an issuer can subscribe to called "issuer_cred_rev". The "issuer_cred_rev" event has information on the issued credential and how it is connected to the revocation registries and some metadata.

This event will fire under two circumstances:

  • Once a credential (with revocation support) is issued.
  • And when a credential is revoked.

The state of the event will correspond with these events, i.e. first it will be "issued" and after revocation it will be "revoked".

Let's take a look at an example event:

{
  "wallet_id": "5df42bab-6719-4c8a-a615-8086435d4de4",
  "topic": "issuer_cred_rev",
  "origin": "tenant faber",
  "group_id": "GroupA",
  "payload": {
    "created_at": "2025-01-30T08:51:18.177543Z",
    "cred_def_id": "QrMaE11MnC6zjKNY1pxbq8:3:CL:8:Epic",
    "cred_ex_id": "af4bad3f-3fcc-47ab-85e6-24224dcb2779",
    "cred_ex_version": "2",
    "cred_rev_id": "2",
    "record_id": "57bd9c72-fa29-4f65-bd89-4e241471073a",
    "rev_reg_id": "QrMaE11MnC6zjKNY1pxbq8:4:QrMaE11MnC6zjKNY1pxbq8:3:CL:8:Epic:CL_ACCUM:53462552-d716-4b0b-8b5c-914a3574d2c4",
    "state": "issued",
    "updated_at": "2025-01-30T08:51:18.177543Z"
  }
}

Taking a look at the payload, there are a few fields we are interested in:

  • "cred_def_id" or credential definition id: The same id the issuer gets when creating a credential definition (also used when issuing credentials).
  • "cred_ex_id" or credential exchange id: This is the same exchange id that can be found in the credential exchange record.
  • "cred_rev_id" or credential revocation id: This is the id that ties the credential to the revocation registry.
  • "rev_reg_id" or revocation registry id: This is the id of the revocation registry the credential was issued against.

The "issuer_cred_rev" event is not the only place this data is available. Under the issuer API, there is an endpoint: GET /v1/issuer/credentials/revocation/record. This endpoint will return the payload object of the "issuer_cred_rev" event:

{
  "created_at": "2025-01-30T08:51:18.177543Z",
  "cred_def_id": "QrMaE11MnC6zjKNY1pxbq8:3:CL:8:Epic",
  "cred_ex_id": "af4bad3f-3fcc-47ab-85e6-24224dcb2779",
  "cred_ex_version": "2",
  "cred_rev_id": "2",
  "record_id": "57bd9c72-fa29-4f65-bd89-4e241471073a",
  "rev_reg_id": "QrMaE11MnC6zjKNY1pxbq8:4:QrMaE11MnC6zjKNY1pxbq8:3:CL:8:Epic:CL_ACCUM:53462552-d716-4b0b-8b5c-914a3574d2c4",
  "state": "issued",
  "updated_at": "2025-01-30T08:51:18.177543Z"
}

This endpoint has three query parameters:

  • "credential_exchange_id"
  • "credential_revocation_id"
  • "revocation_registry_id"

If "credential_exchange_id" is not provided, both the "credential_revocation_id" and "revocation_registry_id" must be provided.

So with the "credential_exchange_id" (from the credential exchange record), an issuer can get the relevant data needed to revoke the credential associated with the exchange id.

[!NOTE] Issuers take note: The most important thing the issuer needs to keep track of is how their credential exchange ids map to credentials they have issued to holders. Without knowing how their exchange ids map to their holders, they won't know which credential to revoke.

Holder requests credential

Now the Holder needs to respond to the credential sent to them. Below the Holder is getting all their connections. We are doing this to get the connection_id of the connection to the issuer. This connection_id can also be gotten from the SSE events.

curl -X 'GET' \
  'http://cloudapi.127.0.0.1.nip.io/tenant/v1/connections' \
  -H 'accept: application/json' \
  -H 'x-api-key: tenant.<Holder token>'

Response:

[
  {
    "alias": "Holder <> Issuer",
    "connection_id": "ac3b0d56-eb33-408a-baeb-0370164d47ae",
    "connection_protocol": "didexchange/1.0",
    "created_at": "2025-01-20T09:56:41.437966Z",
    "error_msg": null,
    "invitation_key": "91ZNSpDgVoV12kHcmUqyp1JmGeKE7oGi9NFd2WMzKt4X",
    "invitation_mode": "once",
    "invitation_msg_id": "6a86e6c7-af25-4e5d-87fe-b42f559b13b9",
    "my_did": "MYhLew4uq58mou8SCTNFYp",
    "state": "completed",
    "their_did": "6wMwbinRJ5XKyBJKm7P5av",
    "their_label": "Demo Issuer",
    "their_public_did": null,
    "their_role": "inviter",
    "updated_at": "2025-01-20T09:56:41.656141Z"
  }
]

Note the connection_id in the above response.

The Holder can then find the credentials offered to them on this connection_id by calling /v1/issuer/credentials with the optional connection_id query parameter:

curl -X 'GET' \
  'http://cloudapi.127.0.0.1.nip.io/tenant/v1/issuer/credentials?connection_id=ac3b0d56-eb33-408a-baeb-0370164d47ae' \
  -H 'accept: application/json' \
  -H 'x-api-key: tenant.<Holder token>'

Response:

[
  {
    "attributes": {
      "Name": "Alice",
      "Surname": "Holder",
      "Age": "25"
    },
    "connection_id": "ac3b0d56-eb33-408a-baeb-0370164d47ae",
    "created_at": "2025-01-20T09:59:29.868946Z",
    "credential_definition_id": "QrHj82kaE61jnB5451zvvG:3:CL:12:Demo Person",
    "credential_exchange_id": "v2-c492cec7-2f2d-4d5f-b839-b57dcd8f8eee",
    "did": null,
    "error_msg": null,
    "role": "holder",
    "schema_id": "FS9J6WZ6KVxwy5eGH32CgM:2:Person:0.1.0",
    "state": "offer-received",
    "thread_id": "9ceeb941-4ebd-42ec-9ffc-ea0b7fe39722",
    "type": "indy",
    "updated_at": "2025-01-20T09:59:29.868946Z"
  }
]

Note the credential_exchange_id and state: offer-received. Additionally, note that the holder and the issuer have different credential_exchange_id references for the same credential exchange interaction.

The Holder can now request the credential, using the credential_exchange_id from the above response, by calling /v1/issuer/credentials/{credential_exchange_id}/request:

curl -X 'POST' \
  'http://cloudapi.127.0.0.1.nip.io/tenant/v1/issuer/credentials/v2-c492cec7-2f2d-4d5f-b839-b57dcd8f8eee/request' \
  -H 'accept: application/json' \
  -H 'x-api-key: tenant.<Holder token>' \
  -d ''

Response:

{
  "attributes": {
    "Name": "Alice",
    "Surname": "Holder",
    "Age": "25"
  },
  "connection_id": "ac3b0d56-eb33-408a-baeb-0370164d47ae",
  "created_at": "2025-01-20T09:59:29.868946Z",
  "credential_definition_id": "QrHj82kaE61jnB5451zvvG:3:CL:12:Demo Person",
  "credential_exchange_id": "v2-c492cec7-2f2d-4d5f-b839-b57dcd8f8eee",
  "did": null,
  "error_msg": null,
  "role": "holder",
  "schema_id": "FS9J6WZ6KVxwy5eGH32CgM:2:Person:0.1.0",
  "state": "request-sent",
  "thread_id": "9ceeb941-4ebd-42ec-9ffc-ea0b7fe39722",
  "type": "indy",
  "updated_at": "2025-01-20T10:02:02.708045Z"
}

The holder request has been sent, and an automated workflow will transition the credential to being stored in the holder's wallet.

We can listen on SSE and wait for state to be done on the topic: credentials

  {
    "wallet_id": "7bb24cc8-2e56-4326-9020-7870ad67b257",
    "topic": "credentials",
    "origin": "multitenant",
    "payload": {
      "attributes": null,
      "connection_id": "ac3b0d56-eb33-408a-baeb-0370164d47ae",
      "created_at": "2025-01-20T09:59:29.868946Z",
      "credential_definition_id": "QrHj82kaE61jnB5451zvvG:3:CL:12:Demo Person",
      "credential_exchange_id": "v2-c492cec7-2f2d-4d5f-b839-b57dcd8f8eee",
      "did": null,
      "error_msg": null,
      "role": "holder",
      "schema_id": "FS9J6WZ6KVxwy5eGH32CgM:2:Person:0.1.0",
      "state": "done",
      "thread_id": "9ceeb941-4ebd-42ec-9ffc-ea0b7fe39722",
      "type": "indy",
      "updated_at": "2025-01-20T10:02:03.043100Z"
    }
  }

Once the state is done, the credential will be in the Holder's wallet. We can list the credential in the wallet by doing the following call as the Holder:

curl -X 'GET' \
  'http://cloudapi.127.0.0.1.nip.io/tenant/v1/wallet/credentials' \
  -H 'accept: application/json' \
  -H 'x-api-key: tenant.<Holder token>'

Response:

{
  "results": [
    {
      "attrs": {
        "Surname": "Holder",
        "Name": "Alice",
        "Age": "25"
      },
      "cred_def_id": "QrHj82kaE61jnB5451zvvG:3:CL:12:Demo Person",
      "cred_rev_id": null,
      "referent": "86dfb6ef-1ff5-41fd-977b-092a1d97e20b",
      "rev_reg_id": null,
      "schema_id": "FS9J6WZ6KVxwy5eGH32CgM:2:Person:0.1.0"
    }
  ]
}

Note: the credential has no reference to a credential_exchange_id. In the wallet context, the referent is the credential id, and is different from the credential_exchange_id used during the credential exchange.

Hooray! 🥳🎉 The holder now has a credential!

Next: Create connection with Verifier

6: Create Connection between Verifier and Holder

Again we first create a connection, this time between the Verifier and Holder. For this connection we use the Out Of Band (OOB) protocol to connect to a tenant that does not necessarily have a public DID.

Note: A verifier is not necessarily onboarded with a public DID - only if they have an issuer role too - so they can only set use_public_did to true if they have configured it themselves.

curl -X 'POST' \
  'http://cloudapi.127.0.0.1.nip.io/tenant/v1/oob/create-invitation' \
  -H 'Content-Type: application/json' \
  -H 'X-Api-Key: tenant.<Verifier token>' \
  -d '{
  "alias": "Verifier<>Holder",
  "multi_use": false,
  "use_public_did": false,
  "create_connection": true
}'

Response:

{
  "created_at": null,
  "invi_msg_id": "754dfe3b-2a08-4863-bfaf-6af7b1e44c99",
  "invitation": {
    "@id": "754dfe3b-2a08-4863-bfaf-6af7b1e44c99",
    "@type": "https://didcomm.org/out-of-band/1.1/invitation",
    "accept": null,
    "goal": null,
    "goal_code": null,
    "handshake_protocols": [
      "https://didcomm.org/didexchange/1.0",
    ],
    "imageUrl": "https://upload.wikimedia.org/wikipedia/commons/7/70/Example.png",
    "label": "FaberIssuer",
    "requests~attach": null,
    "services": [
      {
        "id": "#inline",
        "type": "did-communication",
        "recipientKeys": [
          "did:key:z6MkjtuC76aqXhKQPekfT51GrtURJW8gZPXrGJi8huG6SkNx#z6MkjtuC76aqXhKQPekfT51GrtURJW8gZPXrGJi8huG6SkNx"
        ],
        "serviceEndpoint": "http://multitenant-agent:3020"
      }
    ]
  },
  "invitation_id": null,
  "invitation_url": "http://multitenant-agent:3020?oob=eyJAdHlwZSI6ICJodHRwczovL2RpZGNvbW0ub3JnL291dC1vZi1iYW5kLzEuMS9pbnZpdGF0aW9uIiwgIkBpZCI6ICI3NTRkZmUzYi0yYTA4LTQ4NjMtYmZhZi02YWY3YjFlNDRjOTkiLCAibGFiZWwiOiAiRmFiZXJJc3N1ZXIiLCAiaW1hZ2VVcmwiOiAiaHR0cHM6Ly91cGxvYWQud2lraW1lZGlhLm9yZy93aWtpcGVkaWEvY29tbW9ucy83LzcwL0V4YW1wbGUucG5nIiwgImhhbmRzaGFrZV9wcm90b2NvbHMiOiBbImh0dHBzOi8vZGlkY29tbS5vcmcvZGlkZXhjaGFuZ2UvMS4wIiwgImh0dHBzOi8vZGlkY29tbS5vcmcvY29ubmVjdGlvbnMvMS4wIl0sICJzZXJ2aWNlcyI6IFt7ImlkIjogIiNpbmxpbmUiLCAidHlwZSI6ICJkaWQtY29tbXVuaWNhdGlvbiIsICJyZWNpcGllbnRLZXlzIjogWyJkaWQ6a2V5Ono2TWtqdHVDNzZhcVhoS1FQZWtmVDUxR3J0VVJKVzhnWlBYckdKaThodUc2U2tOeCN6Nk1ranR1Qzc2YXFYaEtRUGVrZlQ1MUdydFVSSlc4Z1pQWHJHSmk4aHVHNlNrTngiXSwgInNlcnZpY2VFbmRwb2ludCI6ICJodHRwOi8vbXVsdGl0ZW5hbnQtYWdlbnQ6MzAyMCJ9XX0",
  "oob_id": "12b5be90-b8fc-40a8-9568-af85b7b31c9b",
  "state": "initial",
  "trace": false,
  "updated_at": null
}

The Holder accepts the invitation using the invitation object shown above. Alternatively, the invitation can be decoded from the base64 payload in the invitation_url field, found after the oob= parameter:

curl -X 'POST' \
  'http://cloudapi.127.0.0.1.nip.io/tenant/v1/oob/accept-invitation' \
  -H 'Content-Type: application/json' \
  -H 'X-Api-Key: tenant.<Holder token>' \
  -d '{
  "alias": "Alice<>Verifier",
  "use_existing_connection": true,
  "invitation": {
    "@id": "754dfe3b-2a08-4863-bfaf-6af7b1e44c99",
    "@type": "https://didcomm.org/out-of-band/1.1/invitation",
    "accept": null,
    "goal": null,
    "goal_code": null,
    "handshake_protocols": [
      "https://didcomm.org/didexchange/1.0",
    ],
    "imageUrl": "https://upload.wikimedia.org/wikipedia/commons/7/70/Example.png",
    "label": "FaberIssuer",
    "requests~attach": null,
    "services": [
      {
        "id": "#inline",
        "type": "did-communication",
        "recipientKeys": [
          "did:key:z6MkjtuC76aqXhKQPekfT51GrtURJW8gZPXrGJi8huG6SkNx#z6MkjtuC76aqXhKQPekfT51GrtURJW8gZPXrGJi8huG6SkNx"
        ],
        "serviceEndpoint": "http://multitenant-agent:3020"
      }
    ]
  }
}'

Response:

{
  "attach_thread_id": null,
  "connection_id": "c750b292-8d3e-467e-8e92-f0ecf19ee97e",
  "created_at": "2025-01-15T06:21:25.555579Z",
  "invi_msg_id": "754dfe3b-2a08-4863-bfaf-6af7b1e44c99",
  "invitation": {
    "@id": "754dfe3b-2a08-4863-bfaf-6af7b1e44c99",
    "@type": "https://didcomm.org/out-of-band/1.1/invitation",
    "accept": null,
    "goal": null,
    "goal_code": null,
    "handshake_protocols": [
      "https://didcomm.org/didexchange/1.0",
    ],
    "imageUrl": "https://upload.wikimedia.org/wikipedia/commons/7/70/Example.png",
    "label": "FaberIssuer",
    "requests~attach": null,
    "services": [
      {
        "id": "#inline",
        "type": "did-communication",
        "recipientKeys": [
          "did:key:z6MkjtuC76aqXhKQPekfT51GrtURJW8gZPXrGJi8huG6SkNx#z6MkjtuC76aqXhKQPekfT51GrtURJW8gZPXrGJi8huG6SkNx"
        ],
        "serviceEndpoint": "http://multitenant-agent:3020"
      }
    ]
  },
  "multi_use": false,
  "oob_id": "b2ae7b58-4ce2-4ee8-81cd-3bba30c6cc8f",
  "our_recipient_key": null,
  "role": "receiver",
  "state": "deleted",
  "their_service": null,
  "trace": false,
  "updated_at": "2025-01-15T06:21:25.555579Z"
}

Listen to Webhooks until this connection is in state: completed.

{
  "wallet_id": "7bb24cc8-2e56-4326-9020-7870ad67b257",
  "topic": "connections",
  "origin": "multitenant",
  "payload": {
    "alias": "Holder <> Verifier",
    "connection_id": "bc8f43aa-5c02-401d-86a0-45d6d08f94b8",
    "connection_protocol": "didexchange/1.0",
    "created_at": "2025-01-20T10:06:01.683789Z",
    "error_msg": null,
    "invitation_key": "Cn3rHufXa94xCUKoSGseXinFSn6oNBb543n15NE6mLzJ",
    "invitation_mode": "once",
    "invitation_msg_id": "4a68ed4b-6a86-45e2-95e9-a76edcd93bc4",
    "my_did": "CnjLLG4U5RPbrYHG4cTMWw",
    "state": "completed",
    "their_did": "2guow2rkGp9wESxZPEWPSJ",
    "their_label": "Demo Verifier",
    "their_public_did": null,
    "their_role": "inviter",
    "updated_at": "2025-01-20T10:06:01.922033Z"
  }
}

Next: Verify Issued Credential

7: Verify Issued Credential

Sending proof request

Once the connection is established, the Verifier can send a proof request.

There are optional restrictions and additional fields that can be added to the proof request, which are beyond the scope of this simple example. For more information, please see our docs for restrictions on proofs.

curl -X 'POST' \
  'http://cloudapi.127.0.0.1.nip.io/tenant/v1/verifier/send-request' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "comment": "Demo",
  "type": "indy",
  "indy_proof_request": {
       "requested_attributes": { 
           "holder_surname": { "name": "Surname", "restrictions":[]},
           "holder_name": { "name": "Name", "restrictions": []},
           "holder_age": { "name": "Age", "restrictions": []}
        }, 
       "requested_predicates": {}   
  },
  "connection_id": "5ef9f4e0-9f98-4e43-aef7-de11da2ccd40"
}'

Response:

{
  "connection_id": "5ef9f4e0-9f98-4e43-aef7-de11da2ccd40",
  "created_at": "2025-01-22T10:12:20.755226Z",
  "error_msg": null,
  "parent_thread_id": "ce5b5597-d3fa-437b-a857-0927694cc4b9",
  "presentation": null,
  "presentation_request": {
    "name": null,
    "non_revoked": null,
    "nonce": "1040329690360437135931695",
    "requested_attributes": {
      "holder_surname": {
        "name": "Surname",
        "names": null,
        "non_revoked": null,
        "restrictions": []
      },
      "holder_name": {
        "name": "Name",
        "names": null,
        "non_revoked": null,
        "restrictions": []
      },
      "holder_age": {
        "name": "Age",
        "names": null,
        "non_revoked": null,
        "restrictions": []
      }
    },
    "requested_predicates": {},
    "version": null
  },
  "proof_id": "v2-57c1bf16-1fc3-4506-b672-8b11580c4920",
  "role": "verifier",
  "state": "request-sent",
  "thread_id": "ce5b5597-d3fa-437b-a857-0927694cc4b9",
  "updated_at": "2025-01-22T10:12:20.755226Z",
  "verified": null
}

Note that the verifier will now have what's called a presentation exchange record in state: request-sent. Pending presentation records can be viewed by calling GET /v1/verifier/proofs, and completed presentation exchange records are deleted by default, but can be preserved by adding an optional save_exchange_record=True field to the request.

Holder responds to proof request

The holder would have received a webhook event on topic proofs, indicating they have received a request. Example webhook:

{
  "wallet_id": "4e0c70fb-f2ad-4f59-81f3-93d8df9b977a",
  "topic": "proofs",
  "origin": "multitenant",
  "payload": {
    "connection_id": "ab1cc0fe-d797-429c-be36-7830a79d52a1",
    "created_at": "2025-01-16T09:59:19.612647Z",
    "error_msg": null,
    "parent_thread_id": null,
    "presentation": null,
    "presentation_request": null,
    "proof_id": "v2-ba39fb0f-4dff-4bce-8db0-fdad3432cc7d",
    "role": "prover",
    "state": "request-received",
    "thread_id": "aea706fd-5492-4ed7-ab1c-1bb9ff309926",
    "updated_at": "2025-01-16T09:59:19.612647Z",
    "verified": null
  }
}

The Holder will now see a presentation exchange record when they call GET on the /v1/verifier/proofs endpoint:

curl -X 'GET' \
  'http://cloudapi.127.0.0.1.nip.io/tenant/v1/verifier/proofs' \
  -H 'accept: application/json'
  -H 'x-api-key: tenant.<holder token>' \

Response:

[
  {
    "connection_id": "ab1cc0fe-d797-429c-be36-7830a79d52a1",
    "created_at": "2025-01-16T09:59:19.612647Z",
    "error_msg": null,
    "parent_thread_id": "aea706fd-5492-4ed7-ab1c-1bb9ff309926",
    "presentation": null,
    "presentation_request": {
      "name": "Proof Request",
      "non_revoked": null,
      "nonce": "234234",
      "requested_attributes": {
        "holder_surname": {
          "name": "surname",
          "names": null,
          "non_revoked": null,
          "restrictions": []
        },
        "holder_name": {
          "name": "name",
          "names": null,
          "non_revoked": null,
          "restrictions": []
        },
        "holder_age": {
          "name": "age",
          "names": null,
          "non_revoked": null,
          "restrictions": []
        }
      },
      "requested_predicates": {},
      "version": "1.0"
    },
    "proof_id": "v2-ba39fb0f-4dff-4bce-8db0-fdad3432cc7d",
    "role": "prover",
    "state": "request-received",
    "thread_id": "aea706fd-5492-4ed7-ab1c-1bb9ff309926",
    "updated_at": "2025-01-16T09:59:19.612647Z",
    "verified": null
  }
]

Note that their role indicates prover, and the state is request-received. Prover is the term used for a holder in a proof exchange. Additionally, note that the prover and the verifier have different proof_id references for the same proof interaction.

The Holder/Prover can now check which credentials match the fields that are requested in the proof request by using the proof_id and making a call to /v1/verifier/proofs/{proof_id}/credentials.

NOTE: If the call is successful, but returns an empty list [], it means that the credentials of the Holder do not match the requested fields in the proof request.

curl -X 'GET' \
  'http://cloudapi.127.0.0.1.nip.io/tenant/v1/verifier/proofs/v2-93e29a31-5eab-4091-9d1d-f27220f445fd/credentials' \
  -H 'accept: application/json'

Response:

NOTE: This response is a list. Each object in this list corresponds to a credential, matching the requested attributes. In this case, the response has only one object, meaning all the requested attributes are found in one credential.

[
  {
    "cred_info": {
      "attrs": {
        "Age": "25",
        "Surname": "Holder",
        "Name": "Alice"
      },
      "cred_def_id": "2hPti9M3aQqsRCy8N6jrDB:3:CL:10:Demo Person",
      "cred_rev_id": null,
      "referent": "10e6b03f-2b60-431a-9634-731594423120",
      "rev_reg_id": null,
      "schema_id": "QpSW24YVf61A3sAWxArfF6:2:Person:0.1.0"
    },
    "interval": null,
    "presentation_referents": ["holder_name", "holder_age", "holder_surname"]
  }
]

We can now use the referent (the referent is the holder's reference to their credential id) from the response above to accept the proof request:

curl -X 'POST' \
  'http://cloudapi.127.0.0.1.nip.io/tenant/v1/verifier/accept-request' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "proof_id": "v2-614a1035-c855-417d-8a8e-0c824bb6ab0f",
  "type": "indy",
  "indy_presentation_spec": {
    "requested_attributes": {
      "holder_surname": {
        "cred_id": "10e6b03f-2b60-431a-9634-731594423120",
        "revealed": true
      },
      "holder_name": {
        "cred_id": "10e6b03f-2b60-431a-9634-731594423120",
        "revealed": true
      },
      "holder_age": {
        "cred_id": "10e6b03f-2b60-431a-9634-731594423120",
        "revealed": true
      }
    },
    "requested_predicates": {},
    "self_attested_attributes": {}
  }
}'
Click to see Response 
{
  "connection_id": "43264326-57a7-4ef4-aa65-906dd9c15961",
  "created_at": "2025-01-22T06:11:46.956062Z",
  "error_msg": null,
  "parent_thread_id": "13a9375e-c124-445d-9242-d77ee54cf47f",
  "presentation": {
    "identifiers": [
      {
        "cred_def_id": "2hPti9M3aQqsRCy8N6jrDB:3:CL:10:Demo Person",
        "rev_reg_id": null,
        "schema_id": "QpSW24YVf61A3sAWxArfF6:2:Person:0.1.0",
        "timestamp": null
      }
    ],
    "proof": {
      "aggregated_proof": {
        "c_hash": "3219322627487542487718476352817657516298296911958347169452423884069641575597",
        "c_list": [
          [2,221,130,248,96,145,3,19,86,111,75,202,101,190,166,101,222,83,181,133,88,134,...]
        ]
      },
      "proofs": [
        {
          "non_revoc_proof": null,
          "primary_proof": {
            "eq_proof": {
              "a_prime": "92597261364394573165798933206533873274818813554675314388834609214520451243506734698448...",
              "e": "13957611453314484376536548594867291175484947973045451726862617289480834912062823268784462725...",
              "m": {
                "master_secret": "113138788366524810935384910670667169176189186849867816774981002913273272990310..."
              },
              "m2": "9527966448141582634179217567781606687146704440935821032302777460114542256740868407661366941...",
              "revealed_attrs": {
                "holder_age": "25",
                "holder_name": "27034640024117331033063128044004318218486816931520886405535659934417438781507",
                "holder_surname": "108415864455171922802944099373800995974825385451497756533671241088029831060565"
              },
              "v": "13310269669535827858183383537992882823597862340798892194315939604086055386082234517559247559..."
            },
            "ge_proofs": []
          }
        }
      ]
    },
    "requested_proof": {
      "predicates": {},
      "revealed_attr_groups": null,
      "revealed_attrs": {
        "holder_surname": {
          "encoded": "108415864455171922802944099373800995974825385451497756533671241088029831060565",
          "raw": "Holder",
          "sub_proof_index": 0
        },
        "holder_name": {
          "encoded": "27034640024117331033063128044004318218486816931520886405535659934417438781507",
          "raw": "Alice",
          "sub_proof_index": 0
        },
        "holder_age": {
          "encoded": "25",
          "raw": "25",
          "sub_proof_index": 0
        }
      },
      "self_attested_attrs": {},
      "unrevealed_attrs": {}
    }
  },
  "presentation_request": {
    "name": "Proof Request",
    "non_revoked": null,
    "nonce": "234234",
    "requested_attributes": {
      "holder_surname": {
        "name": "surname",
        "names": null,
        "non_revoked": null,
        "restrictions": []
      },
      "holder_name": {
        "name": "name",
        "names": null,
        "non_revoked": null,
        "restrictions": []
      },
      "holder_age": {
        "name": "age",
        "names": null,
        "non_revoked": null,
        "restrictions": []
      }
    },
    "requested_predicates": {},
    "version": "1.0"
  },
  "proof_id": "v2-614a1035-c855-417d-8a8e-0c824bb6ab0f",
  "role": "prover",
  "state": "presentation-sent",
  "thread_id": "13a9375e-c124-445d-9242-d77ee54cf47f",
  "updated_at": "2025-01-22T06:28:01.553809Z",
  "verified": null
}

If the proof request is valid, then the verification will complete automatically. Once again, we wait for the exchange to be completed by listening on SSE. Here is an example webhook event for the topic proofs in the done state.

  {
    "wallet_id": "92893658-fe2d-4f2d-8268-a60a601945a9",
    "topic": "proofs",
    "origin": "multitenant",
    "payload": {
      "connection_id": "5ef9f4e0-9f98-4e43-aef7-de11da2ccd40",
      "created_at": "2025-01-22T06:11:46.897536Z",
      "error_msg": null,
      "parent_thread_id": null,
      "presentation": null,
      "presentation_request": null,
      "proof_id": "v2-e83d3d75-9eb1-4d54-a321-7d0d5c5d286e",
      "role": "verifier",
      "state": "done",
      "thread_id": "13a9375e-c124-445d-9242-d77ee54cf47f",
      "updated_at": "2025-01-22T06:28:01.704464Z",
      "verified": true
    }
  }

Verifier can get the proof with all its data by making the following call:

curl -X 'GET' \
  'http://cloudapi.127.0.0.1.nip.io/tenant/v1/verifier/proofs' \
  -H 'accept: application/json'
Click to see Response 
[
  {
    "connection_id": "5ef9f4e0-9f98-4e43-aef7-de11da2ccd40",
    "created_at": "2025-01-22T06:11:46.897536Z",
    "error_msg": null,
    "parent_thread_id": "13a9375e-c124-445d-9242-d77ee54cf47f",
    "presentation": {
      "identifiers": [
        {
          "cred_def_id": "2hPti9M3aQqsRCy8N6jrDB:3:CL:10:Demo Person",
          "rev_reg_id": null,
          "schema_id": "QpSW24YVf61A3sAWxArfF6:2:Person:0.1.0",
          "timestamp": null
        }
      ],
      "proof": {
        "aggregated_proof": {
          "c_hash": "3219322627487542487718476352817657516298296911958347169452423884069641575597",
          "c_list": [
            [2,221,130,248,96,145,3,19,86,111,75,202,101,190,166,101,222,83,181,133,88,134,152,205,154,157,...]
          ]
        },
        "proofs": [
          {
            "non_revoc_proof": null,
            "primary_proof": {
              "eq_proof": {
                "a_prime": "9259726136439457316579893320653387327481881355467531438883460921452045124350673469620...",
                "e": "1395761145331448437653654859486729117548494797304545172686261728948083491206282326878446272...",
                "m": {
                  "master_secret": "11313878836652481093538491067066716917618918684986781677498100291327327294712..."
                },
                "m2": "952796644814158263417921756778160668714670444093582103230277746011454225674086840766136694...",
                "revealed_attrs": {
                  "holder_age": "25",
                  "holder_name": "27034640024117331033063128044004318218486816931520886405535659934417438781507",
                  "holder_surname": "108415864455171922802944099373800995974825385451497756533671241088029831060565"
                },
                "v": "1331026966953582785818338353799288282359786234079889219431593960408605538608223451755924755..."
              },
              "ge_proofs": []
            }
          }
        ]
      },
      "requested_proof": {
        "predicates": {},
        "revealed_attr_groups": null,
        "revealed_attrs": {
          "holder_surname": {
            "encoded": "108415864455171922802944099373800995974825385451497756533671241088029831060565",
            "raw": "Holder",
            "sub_proof_index": 0
          },
          "holder_name": {
            "encoded": "27034640024117331033063128044004318218486816931520886405535659934417438781507",
            "raw": "Alice",
            "sub_proof_index": 0
          },
          "holder_age": {
            "encoded": "25",
            "raw": "25",
            "sub_proof_index": 0
          }
        },
        "self_attested_attrs": {},
        "unrevealed_attrs": {}
      }
    },
    "presentation_request": {
      "name": "Proof Request",
      "non_revoked": null,
      "nonce": "234234",
      "requested_attributes": {
        "holder_surname": {
          "name": "surname",
          "names": null,
          "non_revoked": null,
          "restrictions": []
        },
        "holder_name": {
          "name": "name",
          "names": null,
          "non_revoked": null,
          "restrictions": []
        },
        "holder_age": {
          "name": "age",
          "names": null,
          "non_revoked": null,
          "restrictions": []
        }
      },
      "requested_predicates": {},
      "version": "1.0"
    },
    "proof_id": "v2-e83d3d75-9eb1-4d54-a321-7d0d5c5d286e",
    "role": "verifier",
    "state": "done",
    "thread_id": "13a9375e-c124-445d-9242-d77ee54cf47f",
    "updated_at": "2025-01-22T06:28:01.704464Z",
    "verified": true
  }
]

Hooray! 🥳🎉 Well done, you now know how to issue and verify credentials!

If you would like to learn about revoking credentials, please proceed to the next section: Revoking Credentials.

8: Revoking Credentials

Revoking a credential can take one of two routes depending on the issuer's use case.

Depending on the frequency and volume of credential revocations, issuers may choose to batch publish their revocations or not. Since there is a cost associated with publishing revocations to the ledger, it is recommended that issuers batch revocations when possible.

Automatic Publishing of Revocations

[!WARNING] This endpoint should not be used to revoke more than one credential in quick succession. For multiple revocations, follow the batching route.

The fast and easy way to revoke a credential is to automatically publish the revocation to the ledger, as shown in the example below.

POST /v1/issuer/credentials/revoke

{
  "credential_exchange_id": "v2-af4bad3f-3fcc-47ab-85e6-24224dcb2779",
  "credential_definition_id": "QrMaE11MnC6zjKNY1pxbq8:3:CL:8:Epic",
  "auto_publish_on_ledger": true
}

The endpoint will respond with:

{
  "cred_rev_ids_published": {
    "QrMaE11MnC6zjKNY1pxbq8:4:QrMaE11MnC6zjKNY1pxbq8:3:CL:8:Epic:CL_ACCUM:53462552-d716-4b0b-8b5c-914a3574d2c4": [2]
  }
}

The "issuer_cred_rev" event will fire again with the updated status revoked.

{
  "wallet_id": "5df42bab-6719-4c8a-a615-8086435d4de4",
  "topic": "issuer_cred_rev",
  "origin": "tenant faber",
  "group_id": "GroupA",
  "payload": {
    "created_at": "2025-01-30T08:51:18.177543Z",
    "cred_def_id": "QrMaE11MnC6zjKNY1pxbq8:3:CL:8:Epic",
    "cred_ex_id": "af4bad3f-3fcc-47ab-85e6-24224dcb2779",
    "cred_ex_version": "2",
    "cred_rev_id": "2",
    "record_id": "57bd9c72-fa29-4f65-bd89-4e241471073a",
    "rev_reg_id": "QrMaE11MnC6zjKNY1pxbq8:4:QrMaE11MnC6zjKNY1pxbq8:3:CL:8:Epic:CL_ACCUM:53462552-d716-4b0b-8b5c-914a3574d2c4",
    "state": "revoked",
    "updated_at": "2025-01-30T12:21:16.686124Z"
  }
}

The revocation status endpoint will also be updated to the new state.

GET /v1/issuer/credentials/revocation/record?credential_exchange_id=v2-af4bad3f-3fcc-47ab-85e6-24224dcb2779

{
  "created_at": "2025-01-30T08:51:18.177543Z",
  "cred_def_id": "QrMaE11MnC6zjKNY1pxbq8:3:CL:8:Epic",
  "cred_ex_id": "af4bad3f-3fcc-47ab-85e6-24224dcb2779",
  "cred_ex_version": "2",
  "cred_rev_id": "2",
  "record_id": "57bd9c72-fa29-4f65-bd89-4e241471073a",
  "rev_reg_id": "QrMaE11MnC6zjKNY1pxbq8:4:QrMaE11MnC6zjKNY1pxbq8:3:CL:8:Epic:CL_ACCUM:53462552-d716-4b0b-8b5c-914a3574d2c4",
  "state": "revoked",
  "updated_at": "2025-01-30T12:21:16.686124Z"
}

For emphasis: every credential revoked in this manner will trigger a ledger operation, which incurs a cost. If an issuer has multiple credentials to revoke, it is recommended not to auto-publish to the ledger.

Manual Publishing of Revocations (Batching)

By setting "auto_publish_on_ledger" to false, an issuer can call revoke on all the credential exchange ids they would like to revoke without performing multiple ledger operations.

POST /v1/issuer/credentials/revoke

{
  "credential_exchange_id": "v2-6dbfbeeb-468f-4017-93f7-09c3602b15d4",
  "credential_definition_id": "QrMaE11MnC6zjKNY1pxbq8:3:CL:8:Epic",
  "auto_publish_on_ledger": false
}

The endpoint will respond with:

{
  "cred_rev_ids_published": {}
}

However, the "issuer_cred_rev" event won't fire after every call as it does with "auto_publish_on_ledger": true, because the credential's status will only update when the revocation has been published to the ledger. This is also reflected in the revocation record, as the state remains issued.

GET /v1/issuer/credentials/revocation/record?credential_exchange_id=v2-6dbfbeeb-468f-4017-93f7-09c3602b15d4

{
  "created_at": "2025-01-30T12:49:25.210664Z",
  "cred_def_id": "QrMaE11MnC6zjKNY1pxbq8:3:CL:8:Epic",
  "cred_ex_id": "6dbfbeeb-468f-4017-93f7-09c3602b15d4",
  "cred_ex_version": "2",
  "cred_rev_id": "3",
  "record_id": "287a40fe-a23e-4675-b21f-5b72835b25be",
  "rev_reg_id": "QrMaE11MnC6zjKNY1pxbq8:4:QrMaE11MnC6zjKNY1pxbq8:3:CL:8:Epic:CL_ACCUM:53462552-d716-4b0b-8b5c-914a3574d2c4",
  "state": "issued",
  "updated_at": "2025-01-30T12:49:25.210664Z"
}

Once revocation is called on all the credential exchange ids that need to be revoked, the revocations can then be published to the ledger.

Revocations that were called with "auto_publish_on_ledger": false" are pending publication. An issuer can either publish these revocations or clear the revocation, i.e., not revoke the credential.

Publishing Pending Revocations

The publish revocation endpoint can be used to publish revocations in bulk, or an issuer can be very specific about which revocations they want to publish.

The body sent to the endpoint specifies what needs to be published. This body is a revocation registry to credential map/dictionary.

Each key is a revocation registry ID (rev_reg_id), and its value is a list of credential revocation IDs (cred_rev_id) to be published. The payload below will publish 6 revocations across two registries.

POST /v1/issuer/credentials/publish-revocations

{
  "revocation_registry_credential_map": {
    "WWzcvsHULP1Fkf9GUYRZg8:4:WWzcvsHULP1Fkf9GUYRZg8:3:CL:8:Epic:CL_ACCUM:cd2e0473-31f7-4cde-883d-6fceac1ce0d7": [
      "1",
      "2",
      "3"
    ],
    "WWzcvsHULP1Fkf9GUYRZg8:4:WWzcvsHULP1Fkf9GUYRZg8:3:CL:8:Epic:CL_ACCUM:bf1219ca-75bf-4931-911b-1fe2ace39683": [
      "1",
      "2",
      "4"
    ]
  }
}

Providing an empty list for a registry ID instructs the system to publish all pending revocations for that ID. The payload below will publish all pending revocations for the given registry ID (rev_reg_id).

POST /v1/issuer/credentials/publish-revocations

{
  "revocation_registry_credential_map": {
    "WWzcvsHULP1Fkf9GUYRZg8:4:WWzcvsHULP1Fkf9GUYRZg8:3:CL:8:Epic:CL_ACCUM:cd2e0473-31f7-4cde-883d-6fceac1ce0d7": []
  }
}

An empty map/dictionary signifies that all pending revocations across all registry IDs (belonging to the issuer) should be published.

POST /v1/issuer/credentials/publish-revocations

{
  "revocation_registry_credential_map": {}
}

This endpoint responds with:

{
  "cred_rev_ids_published": {
    "rev_reg_id_1": [1, 2],
    "rev_reg_id_2": [0, 3]
  }
}

The issuer_cred_rev event will also fire for every credential that was revoked after the revocations were published.

Clearing Pending Revocations

The clear revocation endpoint functions in the same way as the publish revocation endpoint. Instead of publishing the revocations, it clears them, i.e., the credential is not revoked and is still considered valid.

The response to the clearing endpoint is also different from the publish endpoint. The clear pending revocation endpoint responds with the still pending revocations.

The payload below will clear the pending revocation on cred_rev_id = 5.

POST /v1/issuer/credentials/clear-pending-revocations

{
  "revocation_registry_credential_map": {
    "CJnbcDL4vBkRzDSw5dS1Pa:4:CJnbcDL4vBkRzDSw5dS1Pa:3:CL:8:Epic:CL_ACCUM:55bd2b4c-672b-4749-b8d3-b1b8137d1012": ["5"]
  }
}

Response of still pending cred_rev_ids for the registry:

{
  "revocation_registry_credential_map": {
    "CJnbcDL4vBkRzDSw5dS1Pa:4:CJnbcDL4vBkRzDSw5dS1Pa:3:CL:8:Epic:CL_ACCUM:55bd2b4c-672b-4749-b8d3-b1b8137d1012": [
      "1",
      "2",
      "3",
      "4"
    ]
  }
}

This call will clear all pending revocations for the given registry ID.

POST /v1/issuer/credentials/clear-pending-revocations

{
  "revocation_registry_credential_map": {
    "CJnbcDL4vBkRzDSw5dS1Pa:4:CJnbcDL4vBkRzDSw5dS1Pa:3:CL:8:Epic:CL_ACCUM:55bd2b4c-672b-4749-b8d3-b1b8137d1012": []
  }
}

Response (no more pending revocations):

{
  "revocation_registry_credential_map": {}
}

This call will clear all revocations for all registries.

POST /v1/issuer/credentials/clear-pending-revocations

{
  "revocation_registry_credential_map": {}
}

Response (no more pending revocations):

{
  "revocation_registry_credential_map": {}
}

Getting Pending Revocations per Revocation Registry

An issuer can get the pending revocations per revocation registry.

This is very easy to do; just call the following endpoint with the rev_reg_id:

GET /v1/issuer/credentials/get-pending-revocations/{revocation_registry_id}

Response:

{
  "pending_cred_rev_ids": [0, 1, 2, 3]
}

The response contains the integers of the cred_rev_ids that are pending revocation for the rev_reg_id called.

Next: Verifying Revoked Credentials

Verifying Revoked Credentials

In order to make sure a credential is not revoked, when making a proof request, it is important to include the non_revoked field. This field defines a time frame where a verifier wants a credential to be valid i.e. not revoked.

To define this time frame, the non_revoked field has two subfields from (optional) and to, both accepting dates in seconds since the Unix epoch. In most cases, the current time should be used, as the verifier is typically interested in credentials that are valid at the time of sending the proof request. Unless, of course, the verifier's use case requires some specific time.

NB: The non-revoked field can be passed as an empty object ("non-revoked":{}), then the application will use the current time when sending the proof request.

The non-revoked field can be specified for all requested attributes (global):

...
"indy_proof_request": {
    "non_revoked": {
      "from": 0,
      "to": 1714727880
    },
    "requested_attributes": {
...

or it can be added to specific attributes individually:

...
"indy_proof_request": {
  "requested_attributes": {
    "surname": { "name": "Surname", "non_revoked":{"to":1714727880}},
...

When both are specified simultaneously, the attribute-specific one will take priority:

...
"indy_proof_request": {
  "non_revoked":{"to":1714727999},
    "requested_attributes": {
      "surname": { "name": "Surname", "non_revoked":{"to":1714727880}},
      "name": {"name": "Name"}
...

In the above snippet, Surname will be checked against the "non_revoked": {"to": 1714727880} value, while Name will be checked against the global value "non_revoked": {"to": 1714727999}.

Verifying non-revoked before the revocation date

When specifying a non_revoked time frame that precedes the revocation time, the proof request will pass. This is by design as the credential was valid in that time frame.

Let's demonstrate:

Listing the holder's credentials:

GET /wallet/credentials

Response:

{
  "results": [
    {
      "attrs": {
        "Surname": "Alice",
        "Age": "25",
        "Name": "Holder"
      },
      "cred_def_id": "BzDvB7StHDD1HQKczybHWC:3:CL:16:Demo_Person",
      "cred_rev_id": "1",
      "referent": "47b18eb8-35f1-4d89-865e-d8355bec77fe",
      "rev_reg_id": "BzDvB7StHDD1HQKczybHWC:4:BzDvB7StHDD1HQKczybHWC:3:CL:16:Demo_Person:CL_ACCUM:73890f4d-42fd-42c5-9a2e-b39fe0358fc6",
      "schema_id": "Pp7wcmoHgeMb3td99E5Yo8:2:Person:0.1.0"
    }
  ]
}

The holder can check the revocation status of their credential:

GET /wallet/credentials/47b18eb8-35f1-4d89-865e-d8355bec77fe/revocation-status

Response:

{
  "revoked": true
}

The holder can see that their credential is revoked. Let's try a verification flow with this credential.

In this example, the verifier sends a request specifying a date/time (2025-01-07 9:00 AM) before the revocation:

POST /verifier/send-request

Request body:

{
  "comment": "string",
  "trace": true,
  "type": "indy",
  "indy_proof_request": {
    "non_revoked": {
      "from": 0,
      "to": 1715065200
    },
    "requested_attributes": {
      "surname": { "name": "Surname" },
      "name": { "name": "Name" },
      "age": { "name": "Age" }
    },
    "requested_predicates": {}
  },
  "save_exchange_record": true,
  "connection_id": "cf45f341-57ad-42bc-b727-6f35e311e7e7"
}

The holder responds:

POST /verifier/accept-request

Request body:

{
  "proof_id": "v2-142c6cd8-a84c-441f-b099-2b39ed6d2099",
  "type": "indy",
  "indy_presentation_spec": {
    "requested_attributes": {
      "age": {
        "cred_id": "47b18eb8-35f1-4d89-865e-d8355bec77fe",
        "revealed": true
      },
      "name": {
        "cred_id": "47b18eb8-35f1-4d89-865e-d8355bec77fe",
        "revealed": true
      },
      "surname": {
        "cred_id": "47b18eb8-35f1-4d89-865e-d8355bec77fe",
        "revealed": true
      }
    },
    "requested_predicates": {},
    "self_attested_attributes": {}
  },
  "save_exchange_record": true
}

The verifier will receive the following webhook on the proofs topic:

{
  "wallet_id": "9a7adafe-3a09-499b-a171-6d39a426bf9e",
  "topic": "proofs",
  "origin": "tenant faber",
  "group_id": "GroupA",
  "payload": {
    "connection_id": "cf45f341-57ad-42bc-b727-6f35e311e7e7",
    "created_at": "2025-01-07T07:21:58.776430Z",
    "error_msg": null,
    "parent_thread_id": null,
    "presentation": null,
    "presentation_request": null,
    "proof_id": "v2-635d106c-7777-4368-bc57-d24f7f878343",
    "role": "verifier",
    "state": "done",
    "thread_id": "b8c70d2b-fe36-4216-9d0a-7c30a6fceb5e",
    "updated_at": "2025-01-07T07:29:10.445048Z",
    "verified": true
  }
}

As you can see, the holder's credential is valid ("verified": true), since the verifier requested a non_revoked timestamp before the revocation took place.

Verifying non-revoked after revocation date

Now, the verifier specifies a date/time (2025-01-07 9:11 AM) after the revocation occurred

POST /verifier/send-request

Request body:

{
  "comment": "string",
  "trace": true,
  "type": "indy",
  "indy_proof_request": {
    "non_revoked": {
      "from": 0,
      "to": 1715065860
    },
    "requested_attributes": {
      "surname": { "name": "Surname" },
      "name": { "name": "Name" },
      "age": { "name": "Age" }
    },
    "requested_predicates": {}
  },
  "save_exchange_record": true,
  "connection_id": "cf45f341-57ad-42bc-b727-6f35e311e7e7"
}

The holder responds:

POST /verifier/accept-request

Request body:

{
  "proof_id": "v2-1894498a-579b-4dd9-9875-856c7f3f4381",
  "type": "indy",
  "indy_presentation_spec": {
    "requested_attributes": {
      "age": {
        "cred_id": "47b18eb8-35f1-4d89-865e-d8355bec77fe",
        "revealed": true
      },
      "name": {
        "cred_id": "47b18eb8-35f1-4d89-865e-d8355bec77fe",
        "revealed": true
      },
      "surname": {
        "cred_id": "47b18eb8-35f1-4d89-865e-d8355bec77fe",
        "revealed": true
      }
    },
    "requested_predicates": {},
    "self_attested_attributes": {}
  },
  "save_exchange_record": true
}

The verifier will receive the following webhook:

{
  "wallet_id": "9a7adafe-3a09-499b-a171-6d39a426bf9e",
  "topic": "proofs",
  "origin": "tenant faber",
  "group_id": "GroupA",
  "payload": {
    "connection_id": "cf45f341-57ad-42bc-b727-6f35e311e7e7",
    "created_at": "2025-01-07T08:02:41.229378Z",
    "error_msg": null,
    "parent_thread_id": null,
    "presentation": null,
    "presentation_request": null,
    "proof_id": "v2-6aaf1b87-45aa-49ee-8e2e-24fe79663fa6",
    "role": "verifier",
    "state": "done",
    "thread_id": "53fe75f8-f4b8-4e22-ae1a-b3a13f2f41c9",
    "updated_at": "2025-01-07T08:18:33.060039Z",
    "verified": false
  }
}

As you can see, the verification has now failed ("verified": false).

Congratulations! You now know how to verify if credentials are revoked or not. 🥳🎉

Self-Attested Attributes

ACA-Py allows a holder/prover to respond to proof requests with self-attested values for requested attributes. This means the prover can provide values that are not represented by credentials in their wallet.

Responding with self-attested attributes

If a prover receives a proof request they can respond with self-attested values. However if there are restrictions on these attributes and the prover responds with self-attested attributes, then the proof will fail.

Let's take a look at how to respond with self_attested_attributes.

Below a verifier will send a proof request, requesting the prover's name and cell_number.

The verifier sends the proof request:

POST  /v1/verifier/send-request

{
  "comment": "Demo",
  "type": "indy",
  "indy_proof_request": {
    "requested_attributes": {
      "given_name": { "name": "name" },
      "cellphone": { "name": "cell_number" }
    },
    "requested_predicates": {}
  },
  "save_exchange_record": true,
  "connection_id": "38f14bc4-4ec5-42bc-8f69-ffe8f792dfaf"
}

Taking a look at the proof request above, the verifier requested two different attributes with attribute referents given_name and cellphone, each requesting attribute name and cell_number respectively.

Take a look at how the prover responds to the proof below, specifically in regard to the attribute referent cellphone. By doing this, the prover is able to provide a value that they don't have in their credentials.

POST /v1/verifier/accept-request

{
  "proof_id": "v2-d0d0e554-ce14-492e-935e-64a7be72ec5b",
  "type": "indy",
  "indy_presentation_spec": {
    "requested_attributes": {
      "given_name": {
        "cred_id": "cb844509-c687-48aa-bbea-dbaecca28a11",
        "revealed": true
      }
    },
    "requested_predicates": {},
    "self_attested_attributes": {
      "cellphone": "0123456789"
    }
  }
}

In the verifier's proof record below, we can see the values the prover responded with can be found under self_attested_attrs.

Note that some large payloads are obfuscated in the following response for readability.

{
    "connection_id": "38f14bc4-4ec5-42bc-8f69-ffe8f792dfaf",
    "created_at": "2025-01-05T11:09:25.161719Z",
    "error_msg": null,
    "parent_thread_id": "839aae9d-29e7-4e7b-aad5-f157d62fe750",
    "presentation": {
      "identifiers": [
        {
          "cred_def_id": "Ph5VFe1yyiwoPKbJmn33d6:3:CL:16:Demo_cred_def",
          "rev_reg_id": null,
          "schema_id": "4vedijxB6SCddvXVYWaTwP:2:Demo:0.1.0",
          "timestamp": null
        }
      ],
      "proof": {
        "aggregated_proof": {...},
        "proofs": [...]
      },
      "requested_proof": {
        "predicates": {},
        "revealed_attr_groups": null,
        "revealed_attrs": {
          "given_name": {
            "encoded": "...",
            "raw": "Alice",
            "sub_proof_index": 0
          }
        },
        "self_attested_attrs": {
          "cellphone": "0123456789"
        },
        "unrevealed_attrs": {}
      }
    },
    "presentation_request": {
      "name": "Proof",
      "non_revoked": null,
      "nonce": "1177112554048610547997440",
      "requested_attributes": {
        "given_name": {
          "name": "name",
          "names": null,
          "non_revoked": null,
          "restrictions": null
        },
        "self_attested": {
          "name": "cell_number",
          "names": null,
          "non_revoked": null,
          "restrictions": null
        }
      },
      "requested_predicates": {},
      "version": "1.0"
    },
    "proof_id": "v2-9d2d22b0-7381-4070-8929-6578399c9ae9",
    "role": "verifier",
    "state": "done",
    "thread_id": "839aae9d-29e7-4e7b-aad5-f157d62fe750",
    "updated_at": "2025-01-05T11:10:55.867679Z",
    "verified": true
  }

Note that the proof is valid (verified: true), and that the prover's cellphone number is available in the self_attested_attrs section as cell_number, the name of the requested attribute.

Implementing Restrictions on Proofs

Both the requested_attributes and requested_predicates fields have a restrictions field. The restrictions field is crucial for specifying conditions on the credentials used to respond to proofs.

Restrictions are applied the same way to requested_attributes and requested_predicates.

Fields to Restrict On

The fields in the list below can be used to apply restrictions to proofs:

  • schema_name
  • schema_id
  • schema_version
  • schema_issuer_did (DID of the entity that issued the schema)
  • issuer_did (DID of the issuer of the credential)
  • cred_def_id (ID of the credential definition)
  • attr::attr-name::value (where attr-name is the name of an attribute in a credential)

Example Payload of Restrictions in Proofs

Below is an example body of a proof request with restrictions on the requested_attributes:

{
  "comment": "test",
  "type": "indy",
  "indy_proof_request": {
    "requested_attributes": {
      "g_name": {
        "name": "name",
        "restrictions": [
          {
            "schema_name": "demo",
            "schema_id": "EoNkijxxJx3RSpnFPQvweP:2:demo:0.1.0",
            "schema_version": "0.1.0",
            "schema_issuer_did": "EoNkijxxJx3RSpnFPQvweP",
            "issuer_did": "8c7aBwbxcN8y6mEKBavq54",
            "cred_def_id": "8c7aBwbxcN8y6mEKBavq54:3:CL:16:cred_def_1",
            "attr::surname::value": "Demo"
          }
        ]
      }
    },
    "requested_predicates": {}
  },
  "save_exchange_record": false,
  "connection_id": "8277590e-ffb5-4437-9226-3a06e1f22031"
}

Applying all of the schema restrictions to a proof request can be overkill. In ACA-Py, the schema_id is made up of the schema name, version, and schema issuer DID. Therefore, if a restriction is applied to the schema_id, then effectively the schema_name, schema_version, and schema_issuer_did restrictions have also been applied.

The last restriction in the list "attr::surname::value":"Demo" ensures that the credential has an attribute named surname with the value Demo.

Example Proof Flow with Restrictions

Below is the result of listing the credentials in a holder's wallet. All of the credentials have the attributes name and surname, but all three of the credentials are based on unique schemas and credential definitions with extra/different attributes.

GET /v1/wallet/credentials

{
  "results": [
    {
      "attrs": {
        "surname": "Demo",
        "name": "Alice"
      },
      "cred_def_id": "3aMAZrkZkA7odBfZkEL15Y:3:CL:16:cred_def_1",
      "cred_rev_id": null,
      "referent": "4225da38-975b-4efc-93a8-32577cc5ba46",
      "rev_reg_id": null,
      "schema_id": "S73FJ6deq6fRhBEfiTckkA:2:Demo1:0.0.1"
    },
    {
      "attrs": {
        "is_cool": "True",
        "surname": "Demo",
        "sa_citizen": "yes",
        "name": "Alice"
      },
      "cred_def_id": "3aMAZrkZkA7odBfZkEL15Y:3:CL:18:cred_def_3",
      "cred_rev_id": null,
      "referent": "76d3f7be-4367-48f4-86d9-05343ddd48d4",
      "rev_reg_id": null,
      "schema_id": "S73FJ6deq6fRhBEfiTckkA:2:Demo3:0.0.3"
    },
    {
      "attrs": {
        "sa_citizen": "yes",
        "name": "Alice",
        "surname": "Demo"
      },
      "cred_def_id": "3aMAZrkZkA7odBfZkEL15Y:3:CL:17:cred_def_2",
      "cred_rev_id": null,
      "referent": "3a100d3e-13cb-457b-8248-ad61589514c3",
      "rev_reg_id": null,
      "schema_id": "S73FJ6deq6fRhBEfiTckkA:2:Demo2:0.0.2"
    }
  ]
}

No Restrictions on Proof Request

When sending a proof request for the attribute surname, with no restrictions, we see that the holder can respond with any one of the credentials:

POST /v1/verifier/send-request

{
  "type": "indy",
  "indy_proof_request": {
    "requested_attributes": {
      "get_surname": {
        "name": "surname",
        "restrictions": []
      }
    },
    "requested_predicates": {}
  },
  "save_exchange_record": true,
  "connection_id": "696f19ef-6cb9-4ca3-a729-9d02f0c47e1e"
}

When the holder checks what credentials can respond to the proof by calling the route below with the proof_id, we see that the holder can respond with any of the credentials, as all of them can satisfy the get_surname property in the requested_attributes.

GET /v1/verifier/proofs/{proof_id}/credentials

[
  {
    "cred_info": {
      "attrs": {
        "name": "Alice",
        "surname": "Demo"
      },
      "cred_def_id": "3aMAZrkZkA7odBfZkEL15Y:3:CL:16:cred_def_1",
      "cred_rev_id": null,
      "referent": "4225da38-975b-4efc-93a8-32577cc5ba46",
      "rev_reg_id": null,
      "schema_id": "S73FJ6deq6fRhBEfiTckkA:2:Demo1:0.0.1"
    },
    "interval": null,
    "presentation_referents": ["get_surname"]
  },
  {
    "cred_info": {
      "attrs": {
        "sa_citizen": "yes",
        "surname": "Demo",
        "name": "Alice",
        "is_cool": "True"
      },
      "cred_def_id": "3aMAZrkZkA7odBfZkEL15Y:3:CL:18:cred_def_3",
      "cred_rev_id": null,
      "referent": "76d3f7be-4367-48f4-86d9-05343ddd48d4",
      "rev_reg_id": null,
      "schema_id": "S73FJ6deq6fRhBEfiTckkA:2:Demo3:0.0.3"
    },
    "interval": null,
    "presentation_referents": ["get_surname"]
  },
  {
    "cred_info": {
      "attrs": {
        "sa_citizen": "yes",
        "surname": "Demo",
        "name": "Alice"
      },
      "cred_def_id": "3aMAZrkZkA7odBfZkEL15Y:3:CL:17:cred_def_2",
      "cred_rev_id": null,
      "referent": "3a100d3e-13cb-457b-8248-ad61589514c3",
      "rev_reg_id": null,
      "schema_id": "S73FJ6deq6fRhBEfiTckkA:2:Demo2:0.0.2"
    },
    "interval": null,
    "presentation_referents": ["get_surname"]
  }
]

Restriction on Schema ID

Below, the proof request has a restriction on schema_id:

POST /v1/verifier/send-request

{
  "type": "indy",
  "indy_proof_request": {
    "requested_attributes": {
      "get_surname": {
        "name": "surname",
        "restrictions": [
          {
            "schema_id": "S73FJ6deq6fRhBEfiTckkA:2:Demo1:0.0.1"
          }
        ]
      }
    },
    "requested_predicates": {}
  },
  "save_exchange_record": true,
  "connection_id": "696f19ef-6cb9-4ca3-a729-9d02f0c47e1e"
}

When the holder checks which credential will satisfy the proof request, only the credential with the schema_id that matches the restriction is returned.

GET /v1/verifier/proofs/{proof_id}/credentials

[
  {
    "cred_info": {
      "attrs": {
        "name": "Alice",
        "surname": "Demo"
      },
      "cred_def_id": "3aMAZrkZkA7odBfZkEL15Y:3:CL:16:cred_def_1",
      "cred_rev_id": null,
      "referent": "4225da38-975b-4efc-93a8-32577cc5ba46",
      "rev_reg_id": null,
      "schema_id": "S73FJ6deq6fRhBEfiTckkA:2:Demo1:0.0.1"
    },
    "interval": null,
    "presentation_referents": ["get_surname"]
  }
]

Restriction on Credential Definition ID

When restricting to the credential definition ID (cred_def_id):

POST /v1/verifier/send-request

{
  "type": "indy",
  "indy_proof_request": {
    "requested_attributes": {
      "get_surname": {
        "name": "surname",
        "restrictions": [
          {
            "cred_def_id": "3aMAZrkZkA7odBfZkEL15Y:3:CL:17:cred_def_2"
          }
        ]
      }
    },
    "requested_predicates": {}
  },
  "save_exchange_record": true,
  "connection_id": "696f19ef-6cb9-4ca3-a729-9d02f0c47e1e"
}

When the holder checks which credential will satisfy the proof request, only the credential with the cred_def_id that matches the restriction is returned.

GET /v1/verifier/proofs/{proof_id}/credentials

[
  {
    "cred_info": {
      "attrs": {
        "sa_citizen": "yes",
        "name": "Alice",
        "surname": "Demo"
      },
      "cred_def_id": "3aMAZrkZkA7odBfZkEL15Y:3:CL:17:cred_def_2",
      "cred_rev_id": null,
      "referent": "3a100d3e-13cb-457b-8248-ad61589514c3",
      "rev_reg_id": null,
      "schema_id": "S73FJ6deq6fRhBEfiTckkA:2:Demo2:0.0.2"
    },
    "interval": null,
    "presentation_referents": ["get_surname"]
  }
]

Restriction on Value of Attribute in Credential

When restricting to an attribute value that is in one of the credentials. In this case, we check that the holder has the attribute is_cool and the value is True.

POST /v1/verifier/send-request

{
  "type": "indy",
  "indy_proof_request": {
    "requested_attributes": {
      "get_surname": {
        "name": "surname",
        "restrictions": [
          {
            "attr::is_cool::value": "True"
          }
        ]
      }
    },
    "requested_predicates": {}
  },
  "save_exchange_record": true,
  "connection_id": "696f19ef-6cb9-4ca3-a729-9d02f0c47e1e"
}

When the holder checks which credential will satisfy the proof, the credential with the is_cool attribute with value True is returned.

GET /v1/verifier/proofs/{proof_id}/credentials

[
  {
    "cred_info": {
      "attrs": {
        "is_cool": "True",
        "surname": "Demo",
        "sa_citizen": "yes",
        "name": "Alice"
      },
      "cred_def_id": "3aMAZrkZkA7odBfZkEL15Y:3:CL:18:cred_def_3",
      "cred_rev_id": null,
      "referent": "76d3f7be-4367-48f4-86d9-05343ddd48d4",
      "rev_reg_id": null,
      "schema_id": "S73FJ6deq6fRhBEfiTckkA:2:Demo3:0.0.3"
    },
    "interval": null,
    "presentation_referents": ["get_surname"]
  }
]

Restriction on Attribute Value Not in Credentials

When restricting to an attribute value that is not in any of the credentials:

POST /v1/verifier/send-request

{
  "type": "indy",
  "indy_proof_request": {
    "requested_attributes": {
      "get_surname": {
        "name": "surname",
        "restrictions": [
          {
            "attr::is_cool::value": "False"
          }
        ]
      }
    },
    "requested_predicates": {}
  },
  "save_exchange_record": true,
  "connection_id": "696f19ef-6cb9-4ca3-a729-9d02f0c47e1e"
}

When the holder checks if they have a credential that satisfies the proof, no credential is returned.

GET /v1/verifier/proofs/{proof_id}/credentials

[]

This indicates to the holder that they do not have any credentials that satisfy the restrictions in the proof request.

Proof Request with Requested Predicates

In ACA-Py, requested predicates are conditions used in proof requests to ensure that certain attributes meet specific criteria without revealing the actual attribute values.

Predicates enable verifiers to request proofs that certain numeric attributes (like age, income, or date) satisfy conditions such as greater than (>), less than (<), greater than or equal to (>=), or less than or equal to (<=) a specified value.

This allows for selective disclosure, enhancing privacy by only proving the required attribute conditions without disclosing the exact values.

The Credential

In order to make a proof request with requested predicates, the credential will need to have an attribute with a value that is an integer. However, if a credential is issued as a string of integers, ACA-Py can convert that to an integer to perform the predicate check.

Furthermore, it is important for the verifier to understand how a credential attribute was set by an issuer to accurately incorporate a predicate in the proof request.

The Proof Request

Let's take a look at the requested_predicates object in the indy_proof_request object.

    "requested_predicates":{
        "name": string,
        "p_type": string,
        "p_value": int,
        "restrictions": <restrictions>,
        "non_revoked": <non_revoc_interval>,
    }
  • The name field is the same as in the requested_attributes; it refers to the attribute of the credential that is being checked.
  • The p_type can be one of the following strings:
    • >= greater or equal
    • <= less or equal
    • > greater as
    • < less than
  • The p_value is the integer that the credential value is being checked against.
  • The restrictions field is used to put restrictions on the credential attribute the prover can respond with. Please take a look at this for more information on restrictions.
  • non-revoked: See the revocation section of the documentation for information on how to check if a credential is revoked.

Example Proof Flow

Below is an example of a proof request with a requested_predicates on the attribute dob (date of birth). The goal of the predicate is to determine if the holder is over the age of 18, without sharing the holder's date of birth.

It has been noted that the verifier needs to understand how a credential attribute has been set to accurately incorporate a predicate. Let's take a look at the credential that has been used here:

{
  "attrs": {
    "dob": "19900101",
    "surname": "Demo",
    "name": "Alice"
  },
  "cred_def_id": "JQKddffbKAw46ERuwLK5cF:3:CL:16:Demo_cred_def",
  "cred_rev_id": "1",
  "referent": "484f7946-b897-4767-914f-9a9357d4c2db",
  "rev_reg_id": "JQKddffbKAw46ERuwLK5cF:4:JQKddffbKAw46ERuwLK5cF:3:CL:16:Demo_cred_def:CL_ACCUM:5c7eb3ed-fbf3-4bf0-a711-ecd8a9365236",
  "schema_id": "4dcSmgArjVgpnfjiy6yNAo:2:Demo_schema:0.1.0"
}

We can see that the dob has the format yyyymmdd, so the verifier can check if a holder's birth date is before the date required to be 18 years old. So the verifier needs to check that: {holder's_dob} <= {date_18_years_ago}.

Issue proof request

 POST v1/verifier/send-request

with body:

{
  "comment": "Demo",
  "trace": true,
  "type": "indy",
  "indy_proof_request": {
    "requested_attributes": {},
    "requested_predicates": {
      "age_over_18": {
        "name": "dob",
        "p_type": "<=",
        "p_value": 20060530,
        "restrictions": [
          {
            "cred_def_id": "JQKddffbKAw46ERuwLK5cF:3:CL:16:Demo_cred_def"
          }
        ]
      }
    }
  },
  "save_exchange_record": true,
  "connection_id": "b993c5db-71bc-4733-a0d9-a72b106ce435"
}

Note the restriction on the cred_def_id above. This ensures the credential comes from a specific issuer and credential definition where we know how the dob has been set.

The holder checks if they have a credential that can satisfy the proof request

GET v1/verifier/proofs/v2-8797794c-cbc0-46be-9a63-2e5d1dc06f6c/credentials

Response:

[
  {
    "cred_info": {
      "attrs": {
        "dob": "19900101",
        "surname": "Demo",
        "name": "Alice"
      },
      "cred_def_id": "JQKddffbKAw46ERuwLK5cF:3:CL:16:Demo_cred_def",
      "cred_rev_id": "1",
      "referent": "484f7946-b897-4767-914f-9a9357d4c2db",
      "rev_reg_id": "JQKddffbKAw46ERuwLK5cF:4:JQKddffbKAw46ERuwLK5cF:3:CL:16:Demo_cred_def:CL_ACCUM:5c7eb3ed-fbf3-4bf0-a711-ecd8a9365236",
      "schema_id": "4dcSmgArjVgpnfjiy6yNAo:2:Demo_schema:0.1.0"
    },
    "interval": null,
    "presentation_referents": ["age_over_18"]
  }
]

The response above shows that the credential returned can be used to respond to the requested predicate age_over_18.

The holder accepts the proof request

POST v1/verifier/accept-request

with body:

{
  "proof_id": "v2-8797794c-cbc0-46be-9a63-2e5d1dc06f6c",
  "type": "indy",
  "indy_presentation_spec": {
    "requested_attributes": {},
    "requested_predicates": {
      "age_over_18": {
        "cred_id": "484f7946-b897-4767-914f-9a9357d4c2db"
      }
    },
    "self_attested_attributes": {}
  },
  "save_exchange_record": true
}

The verifier's proof records

The verifier's webhook events will update on the topic proofs:

{
  "wallet_id": "c32d6406-c200-4b5f-a126-c301ef112477",
  "topic": "proofs",
  "origin": "tenant faber",
  "group_id": "GroupA",
  "payload": {
    "connection_id": "b993c5db-71bc-4733-a0d9-a72b106ce435",
    "created_at": "2025-01-30T09:24:07.325448Z",
    "error_msg": null,
    "parent_thread_id": null,
    "presentation": null,
    "presentation_request": null,
    "proof_id": "v2-284e8535-fa1a-4aac-8121-d192747030a0",
    "role": "verifier",
    "state": "done",
    "thread_id": "17e82614-1304-4c1c-8778-fc81ba18ee4c",
    "updated_at": "2025-01-30T09:29:37.117900Z",
    "verified": true
  }
}

We can see above that the proof request is complete (state: done) and the predicate is satisfied (verified: true).

Let's take a look at the verifier's proof record of the above exchange. Take note of the fact that the revealed_attrs field is empty and the dob attribute has not been revealed.

Note that some large payloads are obfuscated in the following response for readability.


  {
    "connection_id": "b993c5db-71bc-4733-a0d9-a72b106ce435",
    "created_at": "2025-01-30T09:24:07.325448Z",
    "error_msg": null,
    "parent_thread_id": "17e82614-1304-4c1c-8778-fc81ba18ee4c",
    "presentation": {
      "identifiers": [
        {
          "cred_def_id": "JQKddffbKAw46ERuwLK5cF:3:CL:16:Demo_cred_def",
          "rev_reg_id": "JQKddffbKAw46ERuwLK5cF:4:JQKddffbKAw46ERuwLK5cF:3:CL:16:Demo_cred_def:CL_ACCUM:5c7eb3ed-fbf3-4bf0-a711-ecd8a9365236",
          "schema_id": "4dcSmgArjVgpnfjiy6yNAo:2:Demo_schema:0.1.0",
          "timestamp": null
        }
      ],
      "proof": {
        "aggregated_proof": {
          "c_hash": "68083911735211467518460000736130275255547049313413354347790350217175401850873",
          "c_list": [
            [...],
            [...],
            [...],
            [...],
            [...],
            [...]
          ]
        },
        "proofs": [
          {
            "non_revoc_proof": null,
            "primary_proof": {
              "eq_proof": {
                "a_prime": ...,
                "e": "119387358330875008402881076664442056750743658498957523102535902524764053894914591462886392266566631581734329790860931884982192173917395976",
                "m": {
                  "name": "7206276404206857526783008541561244555270605578873171016811937079648008986898196821392261775064255800859371904017451184715729911369974354710297447142369137945850835288326799057347",
                  "dob": "7368174653071291467509243264983933988639387392718531361951217165284981758551875371467982169180823227163338243768448614046815815061385189049986863952228267732988077455166323300407",
                  "surname": "9277859084159715510916067354455243694867960264025518355252696241577763324112627218858326603964984582107518819046740146145718105070048856832278651029469711744592187338261777919850",
                  "master_secret": "15045190061493745649555708650672366392238186118529591984135989041588891839998311612694530842691834680254513558290039881402761553159200315443609127293501475087910035652196924119659"
                },
                "m2": ...,
                "revealed_attrs": {},
                "v": ...
              },
              "ge_proofs": [
                {
                  "alpha": ...,
                  "mj": ...,
                  "predicate": {
                    "attr_name": "dob",
                    "p_type": "LE",
                    "value": 20060530
                  },
                  "r": {...},
                  "t": {...},
                  "u": {...}
                }
              ]
            }
          }
        ]
      },
      "requested_proof": {
        "predicates": {
          "age_over_18": {
            "sub_proof_index": 0
          }
        },
        "revealed_attr_groups": null,
        "revealed_attrs": {},
        "self_attested_attrs": {},
        "unrevealed_attrs": {}
      }
    },
    "presentation_request": {
      "name": "Proof",
      "non_revoked": null,
      "nonce": "824421356049834403305010",
      "requested_attributes": {},
      "requested_predicates": {
        "age_over_18": {
          "name": "dob",
          "non_revoked": null,
          "p_type": "<=",
          "p_value": 20060530,
          "restrictions": [
            {
              "cred_def_id": "JQKddffbKAw46ERuwLK5cF:3:CL:16:Demo_cred_def"
            }
          ]
        }
      },
      "version": "1.0"
    },
    "proof_id": "v2-284e8535-fa1a-4aac-8121-d192747030a0",
    "role": "verifier",
    "state": "done",
    "thread_id": "17e82614-1304-4c1c-8778-fc81ba18ee4c",
    "updated_at": "2025-01-30T09:29:37.117900Z",
    "verified": true
  }

Hooray! 🥳🎉 Well done, you now know how to send and respond to a predicate proof.

Common Steps

This document provides a quick overview of the most common steps: creating wallets, issuing credentials, and verifying credentials. More detailed descriptions of the different steps can be found in the Example Flows document.

Note: It is always helpful to inspect the Swagger UIs to understand the available endpoints, their expected inputs, and the corresponding outputs. If requests fail, check the Swagger UI to ensure you've called the correct endpoint with the correct data. The Swagger UIs are accessible, under a vanilla setup, at:

If you find any model descriptions unclear in the document below, try checking the Swagger UI documentation before opening an issue.

It is also recommended to understand and perhaps set up a webhook listener (refer to our Webhooks doc). This will significantly aid in observing the activities occurring in the ACA-Py instances in the background.

Creating Wallets

The admin "wallet" is already configured as it is not a subwallet on a multi-tenant agent. To create subwallets for tenants, you have to use the tenant admin role. The permissions and routing to the correct ACA-Py instance are handled by acapy-cloud under the hood. You need to provide two things:

  1. Authorization in the header: {"x-api-key": "tenant-admin.APIKEY"}, where tenant-admin is a fixed term representing the role, and APIKEY is the auth token you must know and provide. Note: This auth string is separated by a dot, so keep that in there.

  2. The wallet payload (body) of the wallet you want to create, e.g.,

    {
  "wallet_label": "Demo Issuer",
  "wallet_name": "Faber",
  "roles": ["issuer"],
  "group_id": "API demo",
  "image_url": "https://upload.wikimedia.org/wikipedia/commons/7/70/Example.png"
}

Send this to the /tenant-admin/v1/admin/tenants endpoint. You can omit the roles field altogether or pass "issuer" and/or "verifier". All payloads are documented in Swagger, so if in doubt, consult the Multitenant-Admin docs.

Creating a tenant with roles will update the trust registry by writing an entry for an actor, including wallet details and its associated roles.

If you wish to later update entities roles, you will have to do that again via the tenants admin API, which will handle interacting with the trust registry (see also the Swagger for update tenant).

Creating Schemas

To create schemas and effectively write them to the ledger as well as registering them on the trust registry, use the governance role:

  1. Provide the following authentication header:

    { "x-api-key": "governance.ADMIN_API_KEY" }

    Replace the ADMIN_API_KEY with the actual API key. Keep the dot and recall that governance is a keyword known to acapy-cloud as a role. It will resolve the correct endpoint and available actions based on the role and provided token.

  2. Provide the information about the schema, e.g.:

    {
  "name": "yourAwesomeSchemaName",
  "version": "1.3.7",
  "attributes": ["skill", "age"]
}

    Note that you will need to have a public DID to do so (if your agent lacks one, you can use the governance role to create one: see Bootstrapping the Trust Ecosystem). Run the request with the header from 1. and the payload from 2. against the Governance URL and endpoint /v1/definitions/schemas (POST method). Upon success, the created schema will be returned.

Issuing a Credential

  1. Register a schema (see above)

  2. Register an issuer (create a wallet passing "issuer" as a role - see above)

  3. Issuer creates credential definition

  4. Create a connection between the issuer and prospective holder

    A connection can be created using the /v1/connections/did-exchange/create-request endpoint of the Tenant URL. Here, you will also need to authenticate via the header, e.g., using

    { "x-api-key": "tenant.WALLET_TOKEN" }

    where the WALLET_TOKEN is the bearer token you get from the create wallet response for a tenant wallet.

    Use the issuer's public DID as the their_public_did parameter in the request.

    This will automatically establish a connection between the issuer and the holder, and can be verified by checking the connection records (GET /v1/connections) for either party.

    Alternatively, an OOB invitation can be used to create a connection. Please see this example docs for more details.

  5. Issue a credential from issuer to prospect holder

    1. Create and send a credential authenticating with the issuer. The credential has the form:
    {
  "connection_id": "string",
  "schema_id": "string",
  "attributes": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  }
}

    This should correspond to a schema you created previously, and the connection_id is the ID of the connection you created in the previous step. If you're unsure what that ID is, you can always run a GET request against the connections endpoint to find it.

  6. Accept and store the credential in the holder wallet

  7. Using the holder (authenticating with the holder auth header), issue a GET request against the /v1/issuer/credentials endpoint, providing the connection ID of the connection established above. Note: The connection IDs are unique for each entity, so the connection between the issuer and the holder is one connection with two separate connection IDs - one for the issuer and one for the holder. This will provide you with a credential record that should be in the state of being offered. Providing the connection ID again, you can now use the holder to store the credential by posting to /v1/issuer/credentials/{credential_exchange_id}/store

  8. (Optional) Get yor credentials from your wallet (wallet/credentials) check whether the credential is actually stored. You can also check this via waypoint.

Verifying a Credential

  1. Ensure you followed Issuing a Credential steps to have a wallet with a credential (prover)

  2. Register an entity as a verifier (verifier)

    1. In other words, create or update a wallet, passing the role "verifier"

  3. Create a connection between 1. prover and 2. verifier the same way as in Issuing a Credential

  4. Create a proof request (/v1/verifier/create-request) using the verifier and send it to the prover. Consult the Swagger verifier endpoints. POST to /v1/verifier/send-request with a payload of the following form, replacing the values accordingly (and ensuring they can be covered by the previously created schema and issued credential):

    {
  "connection_id": "string",
  "indy_proof_request": {
    "requested_attributes": {
      "additionalProp1": {
        "name": "string",
        "names": ["string"],
        "non_revoked": {},
        "restrictions": []
      }
    },
    "requested_predicates": {
      "additionalProp1": {
        "name": "string",
        "p_type": "<",
        "p_value": 0,
        "non_revoked": {},
        "restrictions": []
      },
      "name": "string",
      "non_revoked": {},
      "version": "string"
    }
  }
}

  5. Send the proof request.

    1. From the prover, get the proof records using /v1/verifier/proofs and create a proof request you want to send, just as above (same payload format and endpoint).

  6. Accept the proof request.

    1. From the verifier, you can now accept (or reject; see /v1/verifier/reject-request on Swagger for payload) by POSTing to /v1/verifier/send-request, adjusting the payload to:
    {
  "proof_id": "string",
  "indy_presentation_spec": {
    "requested_attributes": {
      "additionalProp1": {
        "cred_id": "string",
        "revealed": true
      }
    },
    "requested_predicates": {
      "additionalProp1": {
        "cred_id": "string",
        "timestamp": 0
      }
    },
    "self_attested_attributes": {
      "additionalProp1": "string",
      "additionalProp2": "string",
      "additionalProp3": "string"
    }
  }
}

  7. (Optional) Wait for the prover and verifier's webhook, using waypoint, and see that the presentation is acknowledged. Alternatively, GET the proof records and check the state field.

Note: There are multiple flows to this "dance". For further details, you may want to refer to the official Aries-RFC.

If you'd like to delve deeper into more of acapy-cloud's capabilities, please see the Example Flows document.

Bootstrapping the Trust Ecosystem with acapy-cloud

[!NOTE] ⚡ The steps described here are now automated during startup. You can skip this guide under a vanilla setup.

1. Prerequisites

Before starting, ensure you have completed the steps in the Quick Start Guide and have all services running.

2. Generate a DID for the Endorser

  1. Access the API through the Governance swagger docs

  2. Authenticate with governance.+APIKEY role

  3. Generate a new DID with a POST to the following API endpoint: /v1/wallet/dids/

  4. An example successful response to generate a DID would look like this:

    {
  "did": "LESjYcQUBF2o3kFy5EUqTL",
  "key_type": null,
  "method": null,
  "posture": null,
  "verkey": "BUxNgHYEYm5bsTEpjo9Dkgr5zGA4feeiuiq32HfqyCKg"
}

  5. Copy the DID and Verkey

3. Anchor New DID to Indy Ledger

  1. Go to Ledger Web Interface
  2. Select Register from DID
  3. Paste the DID and Verkey and select Role Endorser
  4. Click Register DID
  5. DID should be successfully written to the Indy Ledger with a response as below
Identity successfully registered:
DID: LESjYcQUBF2o3kFy5EUqTL
Verkey: BUxNgHYEYm5bsTEpjo9Dkgr5zGA4feeiuiq32HfqyCKg

4. Accept Transaction Author Agreement

  1. Connect to ACA-Py Governance Agent API

  2. Authenticate by setting the x-api-key header with the API Key of the Governance Agent via Swagger/Postman/Insomnia

  3. Get the TAA from the following endpoint /ledger/taa. An example response would be like this:

    {
  "result": {
    "aml_record": {
      "aml": {
        "at_submission": "The agreement was reviewed by the user and accepted at the time of submission of this transaction.",
        "for_session": "The agreement was reviewed by the user and accepted at some point in the user’s session prior to submission.",
        "on_file": "An authorized person accepted the agreement, and such acceptance is on file with the user’s organization.",
        "product_eula": "The agreement was included in the software product’s terms and conditions as part of a license to the end user.",
        "service_agreement": "The agreement was included in the terms and conditions the user accepted as part of contracting a service.",
        "wallet_agreement": "The agreement was reviewed by the user and this affirmation was persisted in the user’s wallet for use during submission."
      },
      "amlContext": "http://aml-context-descr",
      "version": "1.0"
    },
    "taa_record": {
      "digest": "0be4d87dec17a7901cb8ba8bb4239ee34d4f6e08906f3dad81d1d052dccc078f",
      "ratification_ts": 1597654073,
      "text": "This is a sample Transaction Authors Agreement **(TAA)**, for the VON test Network.\n\nOn public ledger systems this will typically contain legal constraints that must be accepted before any write operations will be permitted.",
      "version": "1.1"
    },
    "taa_required": true,
    "taa_accepted": null
  }
}

  4. Copy the text and version from the API response.

  5. Accept the TAA by POSTing to the following API endpoint: /ledger/taa/accept.

    1. Paste the text and version from the previous step into the POST body.

    2. Set the mechanism to service_agreement. A complete POST JSON body example is as follows:

      {
  "mechanism": "service_agreement",
  "text": "This is a sample Transaction Authors Agreement **(TAA)**, for the VON test Network.\n\nOn public ledger systems this will typically contain legal constraints that must be accepted before any write operations will be permitted.",
  "version": "1.1"
}

      This should yield an empty JSON response with a 200 status code.

5. Set Public DID

  1. Go to the Governance interface
  2. Execute the PUT endpoint to set a Public DID: /v1/wallet/dids/public?did=
  3. Use the DID that you anchored to the ledger in step 3
  4. A successful response should look like this. You can also query the Public DID endpoint /wallet/dids/public of the Governance Agent to confirm that the public DID is now set:
{
  "did": "LESjYcQUBF2o3kFy5EUqTL",
  "key_type": "ed25519",
  "method": "sov",
  "posture": "posted",
  "verkey": "BUxNgHYEYm5bsTEpjo9Dkgr5zGA4feeiuiq32HfqyCKg"
}

6. Congratulations

  1. You have now successfully bootstrapped a Trust Ecosystem with acapy-cloud!
  2. You can now write schemas, create credential definitions, manage tenants, and more.

Continue by reading about Governance as Code.

Overview of acapy-cloud Architecture

This document provides a brief overview of the acapy-cloud Architecture, focusing on the two key components: the Admin Agent and the Multi-tenant Agent.

Admin Agent

The Admin Agent and the Multi-tenant Agent are both exposed via the same Swagger UI under the same URL. They are differentiated based on the authorization method, which also specifies a role. For more information on this, refer to the workflows document.

The Admin Agent represents GOVERNANCE, or in a broader sense, the administrative entity. This non-multitenant agent is used for various administrative functions such as creating schemas, managing actors against the trust registry, and managing wallets.

Multi-tenant Agent

Like the Admin Agent, the Multi-tenant Agent is also exposed via the same Swagger UI under the same URL, with distinction made based on the authorization method and role.

The Multi-tenant Agent is designed for sub-wallet and tenant management from the tenant's perspective.

For a more comprehensive understanding of multi-tenancy, please refer to the ACA-Py docs.