This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.


Findy Agency related documentation to get started with the development.

Note: This documentation does not intend to teach readers theoretical background or other aspects of SSI technology. We expect readers to be familiar with basic concepts of SSI. For self-studying SSI and the technology, we recommend excellent material crafed by other authors:

1 - Overview

Findy Agency Overview

Findy Agency provides a Hyperledger Aries compatible identity agent service. It includes a web wallet for individuals and an API for organizations to utilize functionality related to verified data exchange: issuing, holding, verifying, and proving credentials. The agents hosted by the agency operate using DIDComm messaging and Hyperledger Aries protocols. Thus it is interoperable with other Hyperledger Aries compatible agents. The supported verified credential format is currently Hyperledger Indy “Anoncreds” that work with Hyperledger Indy distributed ledger.

You should check out Findy Agency if

  • you are looking for a fully open-sourced, performant Aries compatible identity agency that you can easily run in your local computer
  • you are a web service developer planning to use verified data in your application
  • you would like to build or use a web wallet for individuals instead of mobile application in your use case
  • you want to do experiments quickly without the need to setup or join actual Indy ledger
  • you have experimental attitude and are interested how things can be done differently

However… There are other great solutions you should definitely check out if

  • you expect to find ready-made product with full support and complete documentation
  • you are not interested in running your own agency
  • you are busy to get to production and would rather buy services than craft it yourself.


1.1 - Findy Agency Architecture

Brief description of Findy Agency architecture

Overview of Findy Agency. See more detailed description in findy-agent documentation.

The backend server of Findy Agency consists of three services:

  • core/findy-agent that handles all agent functionality including credential handling and Aries protocols
  • vault/findy-agent-vault that maintains a database of agents’ data. Currently vault has only GraphQL-interface for data queries, that is intended mainly for browser web wallet use.
  • auth/findy-agent-auth that registers and authenticates all agency users.

Reference web wallet implementation is a React app that utilizes standard WebAuthn protocol and browser capabilities to authenticate to backend. Web wallet uses GraphQL to fetch and update agency data.

Wallet login screen.

Service agents are applications that handle verified data on behalf of organizations. Service agents utilize Findy Agency through headless authentication and gRPC API. Samples and reference implementations can be found in agency gRPC helper libraries for go, Typescript or Kotlin.

Agents can be also operated through a CLI, findy-agent-cli, that provides most of the functionality needed for agent and agency manipulation.

2 - Getting Started

Getting started with Findy Agency

2.1 - First Steps with Findy Agency

Instructions how get started with Findy Agency.

Full Agency Setup

Agency services can be setup easily locally using Docker. Check further instructions here. The instructions describe how to launch all the needed backend services in Docker containers together with a simulated ledger. There is also a native development setup instructions for web wallet application which will be needed in order to run web wallet application together with other agents.

Once you have the services running on your computer,


findy-agent-cli is a command-line tool that can be used to

  • register new agents
  • authenticate agents
  • operate agents
    • make connections
    • issue and accept credentials
    • verify and prove credentials
  • operate bots (simple service agents)
  • operate ledger
    • create schemas
    • create credential definitions
  • operate agency
Findy agent cli tool

  findy-agent-cli [command]

Available Commands:
  agency      Manage Agency
  agent       Work with the Cloud Agent
  authn       WebAuthn commands
  bot         Manage Bot
  completion  Generate shell completion scripts
  connection  Manage connections
  help        Help about any command
  new-key     Create a new key for the authenticator
  tree        Prints the findy-agent-cli command structure

      --config string     configuration file, FCLI_CONFIG
  -n, --dry-run           perform a trial run with no changes made, FCLI_DRY_RUN
  -h, --help              help for findy-agent-cli
      --logging string    logging startup arguments, FCLI_LOGGING (default "-logtostderr=true -v=0")
      --server string     gRPC server addr:port, FCLI_SERVER (default "localhost:50051")
      --tls-path string   TLS cert path, FCLI_TLS_PATH
  -v, --version           version for findy-agent-cli

Use "findy-agent-cli [command] --help" for more information about a command.

Check out the dedicated guide for CLI commands to get familiar with the usage.


  • before CLI usage, you need to have a working Findy Agency installation
  • findy-agent-cli is also a reference on how to use the Agency gRPC API with golang. Check the sources for more details.

UI Tool

findy-issuer-tool is a UI tool for

  • making pairwise connections
  • issuing credentials
  • verifying credentials
  • creating schemas and credential definitions.

See setup instructions and usage instructions in project repository.


  • before UI-tool usage, you need to have a working Findy Agency installation
  • findy-issuer-tool works also as a sample implementation for a Findy Agency service agent implemented with JavaScript.

2.2 - Service Agents

Instructions how to get started with service agents.

Service agents i.e. organization agents utilize Findy Agency through its gRPC API. The agent creation and authentication is handled through the headless authenticator, acator, that implements the FIDO2 protocol. Once authenticated, all agent functionality is available to service agents via the core gRPC API, findy-agent-api.

Read more about getting started with service agents from the blog:

You can use our helper libraries for go, Typescript or Kotlin or use directly the gRPC interface with the language of your choice.

You can also find reference implementations, that you should probably explore before starting to implement an agent of your own:

Sample flow: connecting to another agent

Service Agent onboarding and connecting to another agent by creating a connection invitation.

  1. Service Agent (SA) registers with acator tool/library to agency. SA should use a unique user name and the selected authenticator key should be kept secret. Note: the registration needs to be done only once. After the first registration, authentication is done using the same user name and authenticator key.
  2. SA does login with acator tool/library. After successful login, a JWT token is returned to SA.
  3. SA starts listening to agent status events with gRPC API.
  4. SA creates connection invitation using gRPC API.
  5. SA displays/sends/etc. invitation json to another Aries compatible agent (invitee).
  6. Invitee sends connection request to the core agency, that handles the connection protocol on behalf of SA.
  7. Core agency notifies SA when the connection is established. SA can query core agency for the needed connection details and continue with e.g. issuing or verifying data with the new connection.

3 - Agency Deployment

Instructions how to deploy Agency.

The documentation present an overview of Agency deployment architecture and configuration.

Examples and deployment scripts can be found in findy-agent-infra repository:

Also the development environment setup demonstrates how agency services can interact with each other:

3.1 - Configuration

Configuration for agency deployment.

Overall Findy Agency Deployment Architecture

Internet-facing reverse proxy

Nginx, AWS load balancer etc. can work as a reverse proxy. It is recommended to use single domain for request routing to avoid hassle with FIDO2 origin requirements and CORS.

Port 443

/pwaStatic html
/queryvaultGQL queries from PWA. Websocket support needed.
/register, /loginauthWebauthn requires HTTPS. Domain needs to match with PWA.
/a2aagencyEndpoint can be set with the agency’s start up flag.

Port 50051

Agency gRPC interface communication.

Note: Currently also all internal microservices assume gRPC SSL/TLS communication. Unencrypted communication should be enabled within private network in the future.


Sources and more documentation in repository findy-agent

Docker image registry in GitHub Packages.


FCLI_IMPORT_WALLET_FILE/steward.exported/steward.exportedFile path to steward wallet to import
FCLI_IMPORT_WALLET_NAMEstewardstewardSteward wallet name
FCLI_IMPORT_WALLET_FILE_KEYimport-indy-keyKey to wallet file to import
FCLI_POOL_GENESIS_TXN_FILE/genesis_transactions/genesis_transactionsLedger genesis file path
FCLI_POOL_NAME, FCLI_AGENCY_POOL_NAMEfindyfindyLedger pool name
FCLI_AGENCY_HOST_ADDRESSagency.example.comlocalhostHost address as seen from internet
FCLI_AGENCY_HOST_PORT808080Host port as seen from internet
FCLI_AGENCY_SERVER_PORT80808080Server port in local network
FCLI_AGENCY_PSM_DATABASE_FILE/root/findy.bolt/root/findy.boltPSM database file path
FCLI_AGENCY_REGISTER_FILE/root/findy.json/root/findy.jsonHandshake register file path
FCLI_AGENCY_HOST_SCHEMEhttpshttpScheme of the host’s url address
FCLI_AGENCY_ENCLAVE_KEY0ADF..00DCAE""Secure enclave for wallet keys
FCLI_AGENCY_ENCLAVE_PATHfindy-enclave.bolt~/.indy_client/enclave.boltSecure enclave’s filename
FCLI_AGENCY_GRPCtruetrueWhether to enable gRPC service or not
FCLI_AGENCY_GRPC_CERT_PATH/certsrc/ path to gRPC client and server certificates*
FCLI_AGENCY_GRPC_JWT_SECRETrandomstringJWT key for token validation
FCLI_AGENCY_GRPC_PORT5005150051gRPC interface port
FCLI_AGENCY_ADMIN_IDroot039499findy-rootAgency API user ID which is to authorization
FCLI_AGENCY_ENCLAVE_BACKUP~/backups/enclave.bolt.bak""Full file name template for enclave backup file
FCLI_AGENCY_ENCLAVE_BACKUP_TIME04:00""Time of day when enclave backup is started
FCLI_AGENCY_WALLET_BACKUP~/wallet/backups""Path for wallet backups
FCLI_AGENCY_WALLET_BACKUP_TIME05:00""Time of day when when wallet backup is started
FCLI_AGENCY_REGISTER_BACKUP~/backups/findy.json.bak""Full file name template for register backup file
FCLI_AGENCY_REGISTER_BACKUP_INTERVAL20m:30s12hTime interval between backup starts

*Cert path is the root. Both server and client certificates needs be in this folder in their own separated folders named accordingly: server and client.

Configuration files

  • Steward wallet
  • Genesis transactions
  • gRPC client certificate + key (if TLS termination not handled by reverse proxy)
  • gRPC server certificate + key (if TLS termination not handled by reverse proxy)

Data storage (file system)

  • Handshake register (has backup capability): Text file (JSON) for onboarded agent ids
  • PSM database: Bolt db for protocol state machine data
  • Enclave (has backup capability): Bolt db for wallet key data
  • Indy wallets (has backup capability): SQLite db for wallet data
    • in backup recovery wallet must be imported to system with indy SDK API call

findy-agent-auth (FIDO2)

Sources and more documentation in repository findy-agent-auth

Docker image registry in GitHub Packages.


--port8888Port for auth service
--agencylocalhostAgency gRPC service host
--gport5005150051Agency gRPC service port
--domainagency.example.comSite domain name
--originhttps://agency.example.comRequest origin URL
--jwt-secretrandomstringJWT key for access token generation
-sec-filefido-enclave.boltsec enclave file name
-sec-key0A0834BF...DFEAsec enclave master encrypt key
-adminfindy-03029394findy-rootagency admin id
-cert-path/cert""gRPC cert root folder
-sec-backup-file~/backups/fido-enclave.bolt.bak""Full file name template for enclave backup file
-sec-backup-interval1224Time interval between backup checks

Configuration files

  • gRPC client certificate + key
  • gRPC server certificate

Data storage (file system)

  • FIDO enclave it’s key/value database and encrypted by enclave-key which should be transferred as an important secret to the app.
    • Bolt db for user data
    • Uses file system for data storage and backups as well
    • a DB is a single file


Sources and more documentation in repository findy-agent-vault.

Docker image registry in GitHub Packages.


FAV_SERVER_PORT80858085Port for vault service
FAV_JWT_KEYrandomstringJWT key for access token validation
FAV_DB_HOSTxxx.rds.amazonaws.comPostgres db host address
FAV_DB_PORT54325432Postgres db port
FAV_DB_PASSWORDdb-passwordPostgres db password
FAV_AGENCY_HOSTlocalhostlocalhostAgency gRPC server host
FAV_AGENCY_PORT5005150051Agency gRPC server port
FAV_AGENCY_GRPC_CERT_PATH/certAgency gRPC certificate path

Configuration files

  • gRPC client certificate + key
  • gRPC server certificate

Data storage (postgres)

  • Database
    • Postgres (e.g. AWS RDS)
    • Note: Already on first start, vault service expects that the database called vaultexists in the db instance


Sources and more documentation in repository findy-wallet-pwa

Settings (buildtime)

REACT_APP_GQL_HOSTagency.example.comlocalhost:8085Agency vault service host address
REACT_APP_AUTH_HOSTagency.example.comlocalhost:8088Agency auth service host address
REACT_APP_WS_SCHEMEwsswsWebsocket URL scheme

4 - Agency Development

Instructions how to implement changes to agency services.

Coming soon

5 - Contribution guidelines

How to contribute to Findy Network

Contributor License Agreement

You need to sign Contributor License Agreement before making pull requests. Contact Findy Authors for more information.

Pull requests

Use pull requests to contribute code. Pull requests are reviewed through core team before acceptance.


Use issues to report bugs or missing features.


We use master-develop branch model for submitting


Release scripts are used to create master releases

6 - Slides

Presentation Slides

6.1 - Findy Agency — Building Highway to Verified Data Networks

Overview of Findy Agency project for Helsinki Gophers meetup on 3.11.2021

background-image: url( background-size: cover class: center, middle, dark

.image-credit[Photo by Markus Spiske on Unsplash]

Findy Agency —
Building Highway to Verified Data Networks

.img-200[Helsinki Gophers logo]

Helsinki Gophers meetup on 3.11.2021

.author-box.small[Laura Vuorenoja
Technology Strategist @ OP Lab] .author-box.small.github[@lauravuo-techlab] .author-box.small.twitter[@vuorenoja]

layout: true background-image: url( background-size: cover class: center padded-slide name: network

.image-credit[Photo by Pietro Jeng on Unsplash]

Findy Agency

Findy Agency is an identity agent service for individuals and organisations.

It provides functionality and APIs to identity holders for utilizing verified data networks.

Verified data exchange is based on asymmetric cryptography and Decentralized Public Key Infrastructure (DPKI).


  • Findy development team at OP Lab has been researching self-sovereign identity and verified data networks for almost three years now.
  • Findy Agency project has been born as a side product of the research work, multiple PoCs, and demos around this technology.
  • The project codes were published fully as open-source in summer 2021.

Identity Wallet

Credentials, i.e., facts signed by different issuers, are stored in digital wallets.

Using their digital wallet, identity holders can cryptographically prove that the credential data is valid and that they, in fact, own the credential.

Proofs are zero-knowledge and support selective disclosure.


  • Identity holder can be any entity that needs to prove facts about themselves. For example, an individual, an organization or an IoT device can be an identity holder.
  • Zero-knowledge methods allow keeping the issuer signature and parts of the signed message secret. Thus it is possible to:
    • Prove that the attribute exists in the credential, but do not reveal its value.
    • Reveal the value of an attribute without revealing any other attributes.
  • Findy Agency provides the digital wallet service together with needed communication capabilities to identity holders.

layout: false

Verified Data

.img-fill[Trust Triangle]


  • The idea of verified data networks is to utilize cryptography so that different identities can hold and prove facts about themselves digitally.
  • The main concepts in verified data handling are
    • Issuing credentials: signing facts and storing those in one’s digital wallet
    • Prooving credentials: generating proofs from the signed facts and presenting those to counterparties

background-image: url( background-size: cover class: center padded-slide

.image-credit[Photo by NordWood Themes on Unsplash]

Example: Dating Service with Verified Data

Bob creates a profile in an online dating service.

In the service signup phase, Bob needs to verify his gender and age with his digital wallet. He presents proof for his id card.

Verified gender and age are shown to other Service users when they are browsing Bob’s profile.

class: img-fill middle

Example: Dating Service with Verified Data

.img-fill[Trust Triangle]

background-image: url( background-size: cover class: center padded-slide

.image-credit[Photo by Andy Art on Unsplash]

Example: Car Rental Service with Verified Data

Alice wants to rent a car with a self-service rental.

Car rental wants to verify that Alice has a driver’s license before she can make the order.

Alice uses her wallet to present the proof of her license to drive, issued by the police.

class: img-fill middle

Example: Car Rental Service with Verified Data

Trust Triangle

background-image: url( background-size: cover class: center padded-slide

.image-credit[Photo by Hush Naidoo Jade Photography on Unsplash]

Example: Doctor Reservation Service with Verified Data

Bob is booking an appointment with doctor Dan. He has not visited Dan before.

Bob wants to confirm that Dan is not a fake doctor.

Before completing the reservation, Bob sends a proof request to Dan for Dan’s diploma. He can verify that Dan graduated from a respected university.

class: img-fill middle

Example: Doctor Reservation Service with Verified Data

Trust Triangle

class: img-fill

Findy Network Homepage .center.small[Findy Network]


  • A public permissioned blockchain stores the shared data, such as the public keys of the credential issuers. Each network has a set of rules, how this data is maintained and updated.
  • In Finland, we have a joint public-private effort, the Findy cooperative, aiming to run the national Findy network and to maintain the verifiable data registry in the future.
  • Many countries have similar initiatives, such as Germany, Spain and, Canada. EU is also steering legislation in the direction of identity wallets.

template: network

Trust Layer on top of Internet

Founded on trust and security

Increased privacy

Decoupled services

The next step of digitalization


  • Verified data networks make the internet a more secure place.
  • Privacy increases as end-users become the owners of their own data, and they may select which data they want to share.
  • The need for custom integrations between organizations decreases as they can handle the needed data exchange through the network.
    • User and his digital wallet becomes the integration point between services.
  • The use of verified data networks will enable the digitalization of use cases traditionally cumbersome to implement. It will also allow entirely new use cases.

template: network

Used Technologies


indy-sdk and Indy "AnonCreds"

Indy Blockchain

Hyperledger Aries


  • The technology is new and it is evolving rapidly. Some of these tools have likely been replaced when first use cases start in production.
  • DIDComm-messaging is the foundation of all verified data communication. The DIDComm-connection is a secure messaging channel created by exchanging DIDs (identifiers for decentralized, digital identity).
  • Indy-sdk provides the needed cryptographic functionality. It supports the Indy “AnonCreds” credential format.
  • Digital identities are rooted in Hyperledger Indy blockchain, which works together with the indy-sdk-tools.
  • Hyperledger Aries defines the protocol by how identity agents communicate with each other.

class: middle

Used Technologies

.img-fill[Agency Technologies]


  • Each identity holder owns an agent that can handle the credentials and the needed communication with other agents.
  • Depending on the implementation approach, agent functionality can be included in the service as a framework, or agent/agency can run as a separate service.
  • Findy Agency is a multitenant service, i.e., a single installation can host multiple identity agents.
  • At the time Findy Agency development was started, there were no open-source alternatives to choose from. Nowadays, the situation is better, and there are multiple open source frameworks and agencies that support the Aries protocol.

class: img-fill middle center

Architecture Overview

Agency Architecture


  • Multitenant agency serving both individuals and organizations
  • Exceptional cloud-first approach: credential data is stored and handled only in the server-side
  • Secure passwordless authentication via WebAuthn
  • GraphQL for browser, gRPC for API clients
  • Performant microservice architecture implemented with GoLang and gRPC
  • Contanerized microservice images are built with GitHub Actions
  • Fully open-source

Why GoLang?

class: img-fill middle center

.image-credit[Image by Olivier Poitrey]



  • Initially the technology was implemented by crypto-specialists coming from the academic world, and most of the examples were written in Python. As software professionals we knew that building an agency for this purpose would need more performant tools.

  • We thought that Go was the best choice of modern languages when the target is to make network intensive microservices.

  • Our approach using Go is pragmatic. We are not “Go-purists”.

template: network

Go: Highlights 1/2


Concurrency tools

Error handling

Library support: gRPC, graphQL, boltDB, WebAuthn, postgres, cobra, viper, openAPI code generation…

template: network

Go: Highlights 2/2

Tooling: testing, golangci-lint, integration to CI

Cross-platform builds



Multiple development flavors


  • C-bindings to Indy
  • Concurrency handling with channels etc.
  • Excellent library support: gRPC, GraphQL, BoltDB, WebAuthn, postgres, cobra, viper, openAPI generation
  • Error handling
  • Native builds for CLI
  • Tooling: testing, linting, integration to CI

template: network

Go: Challenges

Steep learning curve for developers with JS background and less CLI experience

Multiple repositories

Moving from GOPATH to modules

Short variable names


  • Moving to go packages from GOPATH in the middle of the project, refactoring difficulties
  • Multiple repositories instead of monorepo
  • Package version mismatches
  • Objection among team members

class: center, img-fill



Try it out


6.2 - Test Coverage

Boosting Test Coverage for Microservices

GopherCon UK 2023, London

Slides for GopherCon UK 2023, August 2023

Laura presenting at GopherCon UK 2023. Photo by GopherCon UK.

FooConf 2023, Helsinki

Slides for FooConf 2023, November 2023

Laura presenting at FooConf 2023. Photo by FooConf.

GoLab 2023, Florence

Slides for GoLab 2023, November 2023

Laura presenting at GoLab 2023. Photo by GoLab.

6.3 - CDK-based Continous Deployment for OSS

CDK-based Continous Deployment for OSS

Slides for Tampere AWS User Group Meetup, March 2023

Laura at AWS User Group Meetup (Photo by Harri Lakkala)

6.4 - Introduction to Self-Sovereign Identity

Introduction to SSI in Digital Identity Hack 2023 Kick-off

Slides for Digital Identity Hack 2023 Kick-off


Harri Lainio introducing SSI

6.5 - Hyperledger Global Forum 2022

Overview of Findy Agency project for Hyperledger Global Forum 2022

Slides for Hyperledger Global Forum 2022 breakout session


7 - Videos

Findy Agency Videos

7.1 - GopherCon UK 2023

Boosting Test Coverage for Microservices

7.2 - CDK-based Continuous Deployment for OSS

Laura presents Agency deployment and tooling in AWS Community Day Nordics 2023

7.3 - Introduction to Self-Sovereign Identity

Introduction to SSI in Digital Identity Hack 2023 Kick-off

7.4 - Hyperledger Global Forum 2022 Presentation

Presenting Findy Agency at Hyperledger Global Forum 2022.

7.5 - Findy Agency Presentation

Findy Agency presentation in Aries Working Group Call 2021/12

7.6 - Demo: Alice-Faber-Acme

Example scenario implemented using Findy Agency.

See description and instructions here

7.7 - Demo: Findy Bots

Example scenario implemented using Findy Agency.

7.8 - Interoperability Testing Demo

Demo of Findy Agency interoperability testing

  • Test 1: Findy Agency based issuer/verifier with Lissi Wallet

    A Findy Agency utilizing issuer tool invites Lissi Wallet to form a pairwise connection. Issuer tool sends and verifies a credential with Lissi Wallet.

  • Test 2: Findy Agency Web Wallet with Trinsic Wallet

    Findy Agency Web Wallet user forms a pairwise connection with Trinsic Wallet user. Wallet applications send Aries basic messages to each other.

  • Test 3: ACA-Py based issuer/verifier with Findy Agency Web Wallet

    Aries Test Harness runs ACA-Py-based agents that issue and verify credentials with Findy Agency Web Wallet.

7.9 - SSI-Empowered Identity Provider

Demo of SSI-Empowered OIDC Identity Provider

Open ID Connect (OIDC) is a popular identity protocol for authenticating users and providing identity data for access control. It allows web services to externalize the authentication of end-users by securely signing users in using a third-party identity provider. Findy Agency team has experimented with integrating SSI (self-sovereign identity) agent capabilities to a sample OIDC provider, thus enabling verified data usage in the login flow. The proof-of-concept shows that this approach would allow numerous web applications to switch to SSI-based login with minimal changes.

Read more

7.10 - FTN Issuer Demo

Demo of Finnish Trust Network issuer

A shortcut for SSI adoption is to use existing APIs when issuing credentials and build so-called self-service issuers. In this demo, we showcase how to implement a service for issuing credentials for Finnish Trust Network data.

Read more