> For the complete documentation index, see [llms.txt](https://docs.indicio.tech/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.indicio.tech/developer/indicio-proven-r/proven-integration-guide.md). # Proven Integration Guide The following document describes the major steps to integrate with Proven and incorporate verifiable credentials and decentralized identity into your software, solutions, and workflows. This guide covers all of the necessary information in recommended order and assumes you have general software development knowledge and only an introductory level understanding of decentralized identity technology. This guide starts with an introduction to decentralized identity technology and guides you through architecting your solution. Next, set up a development environment, learn the API and SDK calls, and implement your integration. As your integration nears completion, configure your staging and production environments and test what you’ve developed. Finally, launch, evaluate, maintain, and update your solution. Feel free to skip sections you already understand or to jump straight to what you want to learn. Remember, this is a guide to help you understand how your solution could be implemented, but you should consider your specific requirements, make adjustments, and customize as necessary. Introduction to Decentralized Identity Decentralized identity provides a way for people, organizations, devices, and even AI agents to identify themselves digitally. It also provides a way to reliably trust the information presented by a person or device or a device that has a digital identity. It does this by issuing digitally-signed data in the form of Verifiable Credentials that can be held in digital wallets. The digital signatures ensure that the issuer of the Verifiable Credential can be cryptographically identified and verified and that the integrity of the data in the credential can be verified (i.e., that it hasn’t been altered). Thus, if you trust the issuer of the credential, you can trust the information stored in the credential. This enables digital identity and data to be shared and verified in a fully portable and seamless manner, without reference to certificate authorities, identity providers, or “phoning home” to the source of the data or cross-checking against the same data held in a centralized database. One consequence of decentralized identity is that Verifiable Credentials allow data to be held by the owner (the holder) of the data, typically on their mobile device. This allows people to control who they share their data with and to share it in ways that, depending on the Verifiable Credential format, maximize privacy through selective disclosure and zero-knowledge proofs. This means that decentralized identity solves key challenges for data privacy regulations, such as the European Union’s GDPR. A Verifiable Credential holder can only share their data by consent. They can share data selectively or through zero-knowledge proofs to preserve privacy. This meets the GDPR minimization requirements for consent, data, and purpose (an organization explicitly receives consent from the data owner to use their data, limits the amount of personal data requested, and ties it to a specific use). By being able to verify data cryptographically without needing to centrally store that data, Verifiable Credentials also meet GDPR requirements for security. There are two additional important elements to a credential ecosystem. The first of these is governance. Governance involves establishing and automating trust within a credential use case: Who are the trusted issuers of credentials? Who are the trusted verifiers? What information needs to be presented? These rules are published in machine-readable files by the natural authority for the ecosystem. The second element is how trust is operationally determined, or in other words, how is the cryptography to verify a credential facilitated? The information about credential issuers (such as DIDs and public keys), schemas, revocation, and the linkages between these data types needs to be stored in a trusted location called a Verifiable Data Registry. There are many ways to do this. Three of the most common ways include: 1. Blockchain distributed ledger. The advantage of using a distributed ledger is that it provides credential resilience and longevity. 2. Witness networks. Instead of using a network of nodes to run a ledger, a collection of devices can use other conventions or software to store, secure, and share registry info. 3. Other trust mechanisms. Some methods of storing registry information are simpler than ledgers or witness networks and establish trust in other ways. For example, hosting the information on a web server and using DNS infrastructure to establish trust is relatively straightforward. Depending on the server infrastructure, this may be less robust than a ledger or witness network. In summary, decentralized identity removes the inherently vulnerable processes generally used to identify people and organizations online — processes otherwise known as centralized and federated identity. With the vulnerabilities eliminated, identity and data can be easily and instantly shared and authenticated anywhere using fraud- and AI-resistant ways. ## Architect Your Integration Now that you have learned about the basics of decentralized identity, you’re ready to architect your solution to incorporate decentralized identity and verifiable credentials. Some of the key decisions that you need to make include which DID method(s), schema(s), credential format(s), and protocol(s) to use. You need to assess how many issuers and verifiers are required, how these software agents integrate with existing systems, what wallet(s) and application(s) to use, and a strategy for trust establishment. ### DID Methods DID methods are important because they are used to uniquely identify your software and set up the cryptography at the heart of decentralized identity. They are tied to your trust establishment mechanism. Sometimes they are also tied to credential formats and communication protocols due to the choices developers make when developing decentralized identity software packages. Some popular choices include did:web and did:webvh, did:key, did:sov and did:indy, did:ion, and did:ethr. It is important to note that some decentralized identity systems do not utilize DIDs for identifiers, cryptography, or trust establishment (e.g. mdoc/mDL). ### Schemas One of the most important elements of your integration are the schemas of the verifiable credentials. A schema defines the attributes or data fields in a verifiable credential. These determine which “packets” of information you need to make reusable and verifiable around your system. For example, if you were working with an educational ecosystem, you might need schemas for student IDs, tuition receipts, class completion certificates, and diplomas. Once you’ve identified which schemas you need, you’ll want to identify any existing schemas that you can or need to use. If a suitable or required schema doesn’t exist, you’ll need to create one, which involves specifying which attributes to include in the schema and naming it. Sample User Schema: ``` { "attr_names": [ "user_email", "username", "user_id", "user_roles" ], "name": "User", "version": "1.0" } ``` ### Credential Formats For encoding your schema into credentials, you will need to select one or more credential formats. Each format has pros and cons that may make some formats more suitable than others for your specific use cases. The choice of credential format may be influenced by factors such as regulatory requirements, jurisdictional constraints, privacy and data protection considerations, and interoperability requirements with existing ecosystems or partners. Indicio can assist in navigating these considerations and selecting formats that align with your technical and compliance needs. There are currently four major verifiable credential formats in widespread use; but, like many other technologies, there will be future updates, additions, and competing specifications to consider. After integrating Proven into your solution, you’ll need to schedule a periodic review of available credential formats. #### mdoc/mDL (ISO 18013-5) Mdoc refers to a mobile document, and mDL refers specifically to a mobile driver’s license as defined by the ISO/IEC 18013-5 standard. These formats are primarily used for government-issued digital identity documents, including driver’s licenses and other official credentials. Implementing mdoc and mDL support is more complex than many other credential formats. It typically requires CBOR-based binary encoding, integration with certificate-based public key infrastructure (PKI), and conformance to ecosystem-specific trust frameworks. In addition, participation in many mdoc and mDL ecosystems may require formal approvals or certification processes, particularly for government and regulated deployments. #### SD-JWT VCs SD-JWT Verifiable Credentials are based on the JSON Web Token (JWT) standard and use selective disclosure mechanisms to allow holders to reveal only specific claims during presentation. The format is simpler to implement than some other credential types because it builds on widely adopted JWT tooling and web security primitives. SD-JWT VCs are among the formats approved for use within the eIDAS 2.0 and EUDI Wallet ecosystems. However, they do not currently provide native support for zero-knowledge proofs or cryptographic unlinkability across presentations. As a result, deployments that require reduced correlation across repeated use often rely on issuing credentials in batches or using additional operational controls. #### JSON-LD VCs (W3C VCs) JSON-LD Verifiable Credentials are defined by the W3C Verifiable Credentials Data Model and use JSON-LD to represent credential data in a flexible, extensible format. They are commonly used in decentralized identity systems and support a wide range of credential types and use cases. JSON-LD credentials can be issued to a holder and presented across systems without being bound to a single platform. However, in their base form, they do not provide native support for selective disclosure or zero-knowledge proofs. Implementations that require these privacy-preserving features typically rely on additional cryptographic extensions or alternative credential formats. #### AnonCreds AnonCreds (Anonymous Credentials) are a credential format designed to provide strong privacy guarantees, including selective disclosure, zero-knowledge proofs, and cryptographic unlinkability across repeated presentations, making them well-suited for privacy-sensitive use cases. Many current implementations rely on supporting infrastructure such as distributed ledgers for credential metadata and revocation, as well as DIDComm-based communication protocols. ### Protocols There are some major protocols in use with verifiable credentials, which are used for issuing credentials, requesting and sharing presentations, and, with DIDComm, performing other operations related to decentralized identity. Typically, implementations start with one or a small number of protocols. Additional protocols can be added later to improve system interoperability or when they’re needed for their unique capabilities. They can also be added to create implementations with novel properties. #### OID4VC OID4VC (OpenID for Verifiable Credentials) defines standardized protocols for both verifiable credential issuance (OID4VCI) and verifiable credential presentation (OID4VP). It builds on OpenID and OAuth flows that are already familiar to many developers, making integration straightforward. Because it leverages existing authentication patterns and infrastructure, OID4VC enables secure credential exchange with minimal additional overhead. One con to using OID4VC is that it does not establish a persistent connection, so additional interactions will require new URLs. #### DIDComm DIDComm includes protocols for issuance and verification, among others. DIDComm’s major strength is that it can maintain a persistent connection, which allows two connected agents to carry out additional operations and utilize established trust over time. #### BLE, NFC, WiFi Aware While implemented in different ways, these are all “proximity” protocols–protocols used when two software agents are within close range of each other. This is simultaneously their strength and weakness. #### DC API The Digital Credentials (DC) API is supported by both Android and iOS and allows for simpler verifiable credential support on websites. ### Issuers After you have determined how to manage all of the previous considerations, you can plan for credential issuance in your solution. Generally speaking, you need one credential issuing agent for each distinct entity making verifiable statements. You also need to consider where in your workflow you need to collect and validate data and when it needs to be issued to a holder’s wallet. This will determine where code updates or additions will need to be made in your existing system. ### Verifiers The next step is to plan for credential verification in your solution. Again, generally speaking, you need one verifying agent for each entity that needs to verify credential data (through the use of verifiable presentations). For each verifier, determine which credentials and credential attributes you need. You need to decide where in your workflows the data needs to be verified and ingested so you can plan for updates or additions. ### Wallet and Application Strategy When considering your wallet and application strategy, there are several important questions to answer. Will you use an existing wallet (such as Holdr+)? Will you white-label an existing wallet? Will you build or modify an app to include wallet functionality using an SDK (such as Indicio’s Holdr SDK)? Do you need to support multiple apps or wallets? ### Trust Establishment Aside from the cryptography involved with issuing and verifying credentials, you also need a way to identify which parties are trusted. There are various ways to do this, including DIF Credential Trust Establishment, ToIP Trust Registries, x.509 certificate chains with VICAL, and OAuth. ## Configure Development Environment To integrate with Proven, you will need to install your own copy of Proven and configure it to meet your specific needs. The following instructions are one way you can install Proven by yourself. If you need assistance or other installation options, please get in touch with us — Proven works with a wide variety of hosting options. Follow the instructions in the GC Proven User Installation Guide to get a baseline Proven installed. \ Using the example instructions in the above document as a guide, add one or more schemas as needed for your application. You might also need to add an invitation for use by your application. Use the following steps if needed: 1. Log in to the Proven UI. 2. Click **INVITATIONS** in the main menu. 3. Click the large **+** button in the lower right corner. 4. Fill in the fields. Start with the following common values, then adjust to your preferences as needed: 1. OOB Invitation: **True** 2. Protocol: **DID Exchange 1.1** 3. Alias: your choice, used to refer to the invitation within Proven 4. Invitation Mode: **Multi** 5. Uses: leave blank for no limit or enter a specific number (e.g. 5000) to cap how many times the invitation will be used 6. Accept: **Auto** 7. Public: **False** 8. Their Role: your choice, could be used to categorize connections 9. Their Label: your choice, usually used by other agents as a friendly name for this agent 10. Workflow Status: **Active** 11. Description: your choice, usually a short reminder of what this invitation was created for 12. Purpose: your choice, this is a unique “handle” to use when linking invitations to specific workflows or behavior 13. Active Starting Time: unused in this version 14. Active Ending Time: unused in this version 15. Once the invitation is created, click on the new invitation, then copy the new invitation URL into your application. Congratulations, you now have an instance of Proven that you can use for learning, experimentation, and development! ## Learn Proven API and Holdr SDK Calls Once you’ve architected your solution and configured an instance of Proven to use in development, it’s time to learn how to use Proven and the Holdr SDK. ### Proven The [Indicio Proven API Tutorial](https://indicio.gitbook.io/indicio-api-docs/sDoMLaDjYpI97bDybeEO/indicio-proven-r/how-to-guides/indicio-proven-api-tutorial) demonstrates how to connect, issue, and verify an AnonCreds credential using a Proven Agent and the Holdr+ Mobile Wallet application. See [API Calls for OID4VCI and OID4VP SDJWT](https://indicio.gitbook.io/indicio-api-docs/sDoMLaDjYpI97bDybeEO/indicio-proven-r/how-to-guides/api-calls-for-oid4vci-and-oid4vp-sdjwt) for instructions to issue and verify an SD-JWT VC or JWT VC using a Proven Agent and then using the SDK. See [Indicio Proven API Documentation](https://indicio.gitbook.io/indicio-api-docs/sDoMLaDjYpI97bDybeEO/indicio-proven-r/how-to-guides/indicio-proven-api-documentation#credentials-read-credential-issuance-by-id-json-ld) to view the API calls to issue and verify JSON-LD type credentials using a Proven Agent. You can also refer to the [Indicio Proven API Reference](https://indicio.gitbook.io/indicio-api-docs/sDoMLaDjYpI97bDybeEO/indicio-proven-r/how-to-guides/indicio-proven-api-documentation) to learn more about individual API calls. ### Holdr SDK The Holdr [Mobile SDK Documentation](https://indicio.gitbook.io/indicio-api-docs/sDoMLaDjYpI97bDybeEO/mobile-solutions/mobile-sdk) describes how to install, configure, and use the Holdr SDK. ## Implement Your Integration Now that you have a solution architecture, a development system, and some experience with Proven and the Holdr SDK, you are ready to implement your integration. We’ll describe a process that works well for us and then share some useful tips, hints, and information. ### A Basic Integration Process We like to follow these high-level steps during our integrations: 1. Publish schemas and configure your Proven agent(s) to use them. 2. Issue a test credential using dummy data to an existing wallet (such as Holdr+). 3. Use Holdr+ to present the test credential to your Proven verifier. 4. Write code in your existing system to retrieve and collect data for a credential and then call the Proven API to issue the credential to the existing wallet. 5. Write code in your system to receive webhooks. Try out these endpoints manually. 6. Configure the webhooks in your Proven verifier to send verifiable presentation data to your system’s new endpoints. 7. Now that real credential data can be used to create credentials and real presentation data can be ingested by your system, you can start working on your own wallet application instead of using Holdr+. 8. Create a white label version of Holdr+, add the Holdr SDK to your existing application, or begin coding a new application using the Holdr SDK. ### Integration Tips, Hints, and Information Keep the following tips and information in mind while you are integrating decentralized identity into your solution using Proven:
1. (Developer) licenses 1. Expiration - Proven licenses include an expiration date. To ensure that your solution is running within its license agreement and continues to function, make careful note of when your software license expires. 2. Renewal - Although your license includes a short grace period, you will have more success if you begin the renewal process before your grace period begins so that your renewed license is ready to go right when you need it. 3. Enforcement - Indicio Proven and the Indicio Holdr SDK will stop working after their license grace periods expire, usually after 60 days. 2. Development tips & tricks 1. Source control - We recommend keeping your code in a source control solution to make sure that your code is versioned and backed up. 2. Backups - We also recommend performing periodic backups of the different parts of your solution to help provide a robust system that can survive most emergencies or disasters. 3. Indicio Support 1. For any support-related issues that you encounter, please feel free to directly contact anyone at Indicio that you already have contact with, or use our Indicio support email, , to share your issues and we will get back to you as soon as we can. 4. Testing during development 1. Unit/integration/E2E testing 1. Although there is a later section focused entirely on testing, it is wise to write many of your tests (both automated and test scripts for humans) during your development phase. 2. Happy/unhappy path testing 1. During the development process, it is also wise to record what successful and unsuccessful outcomes are possible and how to trigger those behaviors. Having repeatable test scripts to periodically check your system will be valuable. Configure Staging Environment Now that your solution has been developed and integrated with Proven, it is time to build a staging environment for testing of a production-like environment (which can also be used for demonstrations). While it’s possible to use the Proven instance created for development for this purpose, we recommend using a different environment for staging so that development efforts do not compromise your efforts to test and demonstrate your solution. The Proven Staging environment is built in the same way as instructed in the Configure Development Environment section. Be sure to add all schemas that were included and needed from your development environment and remember to incorporate any learnings that you have experienced along the way. The Proven Staging environment should be nearly an exact replica of what you built for Development. If you are using Hyperledger Indy as your VDR, you will want to configure your staging environment to use a stable network (such as the Indicio DemoNet) or, for testing that is closer to production configuration, a production network (such as the Indicio MainNet). The schemas used in development can be reused and simply added to the Proven Staging instance as needed (although the schema ID may be different if you are using a different network than you did in development), but the invitations will be different. Configure Production Environment Once you have completed the Staging phase, it’s time to begin the production phase. The Proven Production environment is built the same as the Proven Staging environment but with a few additional recommended security hardening measures to ensure resilience, integrity, and operational reliability. **Proven Server Hardening Recommendations:** 1. Secure passwords 1. Follow the instructions for setting up Proven to ensure that all passwords included in Proven are secure. 2. Firewall 1. Enforce a strict default-deny inbound policy. 2. Allow only the minimum required ports (e.g., 80, 443, 22 and possibly 8150 if needed for swagger API access). 3. Restrict SSH access to trusted IPs. 4. DDoS protection - Implement request-rate limiting on ingress with a cloud-native tool like Cloud Armor. 3. Monitoring 1. Implement real-time monitoring for at least the following: 1. CPU 2. memory 3. disk space 4. network behavior 2. Daily Checks 1. A daily smoke test helps ensure that your services are always available for your customers. 4. OS Security 1. Apply all OS security patches regularly 5. Access control 1. Limit the number of users with access to the server (but have at least two). 6. Enforce MFA for all admin accounts. 1. Backups 7. Automated daily backups. Testing Before Launch Testing your verifiable credential solution and workflows should include standard testing procedures as well as tests to cover some unique decentralized identity considerations. ### Standard Testing There are a number of testing practices that we recommend in order to ensure that a solution is complete, robust, and resilient. #### Code Tests We recommend unit, integration, and end-to-end (E2E) tests of your code to verify that new functionality works and that you don’t have regressions. #### Technical Tests Conduct performance and security tests of your system. **Performance tests:** * Load testing * Stress testing * Spike testing * Endurance testing * Scalability testing **Security tests:** * Penetration testing * Vulnerability scanning * Fuzz testing * Risk assessments #### Usability and Approval Conduct user and acceptance tests to ensure the solution is usable and that you’ve delivered a satisfactory end product. ### Decentralized Identity Testing There are some unique considerations for testing solutions and workflows that include decentralized identity. #### VDR (Verifiable Data Registry) VDRs underpin the trust of your solution, so reliability, security, and compliance are especially important. This also means that it is riskier to “roll your own” implementation and the focus of your efforts should be on properly installing, configuring, and testing an existing registry solution. Some key things to test include correct operation, performance, availability, and data minimization. As some VDRs (such as Hyperledger Indy) use nonstandard ports, you will need to ensure that your firewall rules allow access to the VDR. #### Schemas Schemas are crucial for semantic interoperability of issued credentials, so it is important that validation, governance, and interoperability are tested. Begin testing by ensuring the different parts of your system are using matching schema IDs. #### Revocation Revocation allows trust in the system to increase because it provides a way to handle inaccurate or expired information. Testing for resilience, availability, and performance is especially crucial for revocation. #### Mediator Because mediators provide stable endpoints and collect messages for your mobile software, making sure they are stable and performing well is crucial. Indicio can assist with generating load to test mediator capacity and stability. #### Interoperability Testing If your solution is open to multiple parties, apps, or software versions, you’ll need to test the various combinations that could occur in real-world usage. Using official test suites is very useful for interoperability testing. #### DPIA (Data Protection Impact Assessment) Certain deployments, particularly in regulated or government environments, may require a Data Protection Impact Assessment. Your organization can approach Indicio for guidance and assistance, including supporting documentation on processing purposes, data flows, and technical safeguards, as well as explanations of how verifiable credential-based designs support privacy-by-design and data minimization principles. #### Governance Governance defines how trust is established, enforced, and maintained over time within a verifiable credential ecosystem. At a minimum, your system should explicitly control which credential issuers are trusted and under what conditions their credentials are accepted. Beyond issuer trust, governance considerations typically include policy enforcement, operational readiness, onboarding and offboarding of participants, transparency into trust decisions, and alignment with applicable legal and contractual frameworks. These elements should be clearly defined and validated before production deployment to ensure consistent and predictable behavior across environments. ## Launch If you have existing deployment and launch procedures in place, it is wise to continue using them. The following launch steps or considerations will help ensure that the additional decentralized identity integration also goes smoothly. ### Phased Approach Consider a soft or incremental launch, where a limited set of users or features is introduced at one time in order to reduce the risk of the new launch. ### Technical Preparation Your technical team should be prepared to support the launch of your integrated solution by having monitoring configured, a support plan in place, and establishing rollback or contingency plans if anything goes wrong during or following the launch. ### Training and Other Materials There is more to a successful launch than the technical rollout of new technology. Operations, support, customer service, and even marketing and sales departments should be aware of and prepare new processes and materials for the changes introduced with decentralized identity. * **Change management** so everyone involved, especially customer-facing employees, knows what has been updated and can guide users to successfully use the system. * **Training materials** for those with a role that requires more than simple awareness of the updated solution. * **Quick start guides** may be useful for employees or customers. * **Full instructions** are useful for documenting workflows and providing detailed guidance. * **FAQs** provide guidance in an easy-to-digest format. * **Signage** is often necessary where solutions have a physical presence. * **Promotion** can be key to the success or failure of a new solution launch. If the public is unaware of or doesn’t understand the new offering, it may fail to meet utilization goals. * **Marketing and sales** materials are important for solutions that need to be sold before they are utilized by end users. ## After Launch ### Gather Data and Feedback Collecting and analyzing data from monitoring systems allows you to gauge the solution’s performance. After the solution has launched, it is also important to immediately and then periodically gather feedback from those using and supporting the system to gauge their impressions and identify any signs of trouble. ### Applying Security Updates Security updates are regularly released for nearly all actively maintained software, and Proven and the software it relies on are no exception. We recommend establishing a monthly (at a minimum) cadence of applying security updates. ### Updating Your Software You will need to consider at least two major portions of your solution that might need to be updated: Proven Updates: Updates to Proven will include improvements and new features that you might want to add to your solution. Regularly check for updates to Proven and consider if and when to upgrade to later versions. Solution Updates: Your solution might need changes and improvements. Establish a regular evaluation of your solution and perhaps a roadmap for the development of improvements and upgrades. ## Summary Integrating Proven allows you to add powerful decentralized identity functionality to your solution using familiar patterns, such as APIs and SDKs, unit and integration tests, Docker and Kubernetes, and more. As with all guides, however, this guide cannot describe every situation, requirement, step, or potential solution. Contact us if you have questions or would like assistance integrating Proven into your solution. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.indicio.tech/developer/indicio-proven-r/proven-integration-guide.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.