VRS Roundtrip Testing Guide

CARO Test Environment Guide for VRS

This document describes the CARO account set-up for testing by VRS providers.
Please follow the instructions in the API Documentation for VRS providers to use and configure the required APIs.

This document will be updated continuously. Please check back frequently, as new features and functionalities will be added to the application and explained here.

Development Status

The current application is a beta version, which is continuously being developed further.

If you are in the process of testing CARO, we would love to hear your feedback. Which functionalities or info screens are useful to you? What should we add or remove? How can we make your life easier? Please get in touch through one of the means detailed at the bottom of this page.

VRS Test Account Set-up

In practice, a VRS provider needs to be granted access by their customer into their trading partner account. Subsequently, VRS can access the account via the APIs VP Generation and VP Verification.

For testing purposes, we take a short-cut. Spherity provides you with two mock trading partner accounts to mimic both the requester and the responder roles. The requester account represents wholesalers (or dispensers) sending a Product Identifier (PI) Verification request. The responder account represents manufacturers responding to a PI Verification request. In each account you can find the test trading partner decentralized identifiers (DID). Each unique identifier effectively represents a specific imaginary trading partner within the system.

ONLY for API endpoint testing has Spherity created DSCSA ATP test credentials within our system for both requester and responder accounts. Note that these test credentials have not been issued by our integrated Credential Issuer, Legisym, as this is not required for API endpoint testing.

The web app resides on api.caro.vc. Using the email address provided by you, we will invite you to your test accounts. You will then be able to log in and start testing.

Test Scenarios

OCI has scoped relevant credentialing test cases. Spherity continues to be actively involved in this process. We update CARO as needed to accommodate changing recommendations.

As it stands, CARO enables testing based on:

• valid ATP credential
• expired ATP credential
• revoked ATP credential
• invalid issuance date of ATP credential
• invalid issuer of ATP credential
• invalid proof (i.e. invalid signature in ATP credential)
• no ATP credential

Each of these scenarios is associated with its own DID. Thus, by choosing a DID, you also select its directly associated verifiable credential (VC). The DID naming in our CARO test set-up indicates the state of the credential, i.e. valid or invalid.

Both the requester and responder test accounts enable the same set of test cases. This allows you to test success and failure scenarios on either side of the VRS roundtrip, i.e. the requestor and responder side, depending on the chosen DIDs per test run.

The requester and responder DIDs with an associated valid ATP credential will enable a test of the happy path scenario, i.e. a complete successful VRS roundtrip. Use of any other DID will result in an error message as specified by OCI's Digital Wallet Conformance Criteria.

Here is an illustration of two roundtrip scenarios:

• successful VRS roundtrip, as both requester and responder have valid credentials
• failed VRS roundtrip, as the responder has an invalid credential (CARO will throw an OCI-specified error)

Please note

• The list of provided DIDs in your CARO trading partner account includes an issuer DID. Please ignore this DID as a VRS tester.
• Whilst the current test set-up includes the above-mentioned ATP credentials, identity credentials have not been pre-populated, as this is not required for API endpoint testing.

Testing Process Flow

1. Decide which DID in the requester and responder accounts to use depending on the scenario you want to test.
2. Generate the Verifiable Presentation (VP) of the DSCSA ATP Credential by calling the VP Generation API. Refer to our API documentation for details.
3. Verify the VP of the DSCSA ATP Credential by calling the VP Verification API. Refer to our API documentation for details.

App Interface

As a participant of the VRS testing exercise, you assume TWO roles within the CARO app. This means that you will see the interface designed for service providers (who you actually are) AND the interface designed for trading partners (who you pretend to be).

• Refer to our user guide for VRS for information on the interface for VRS.
• Refer to our user guide for trading partners for information on the interface for trading partners.

Further Resources

• CARO API Documentation
• OCI introductory resources including Getting Started with VRS Testing

VRS User Guide

CARO User Guide for VRS Providers

This document walks you through the functionalities of the CARO app, Spherity's Credentialing Service for Authorized Trading Partners (ATP), to enable you to navigate the user interface as a VRS provider. It does neither explain any technical details of the Credentialing Service nor provide guidelines for the technical implementation of CARO.

This document will be updated continuously. Please check back frequently, as new features and functionalities will be added to the application and explained here.

If you are looking for a high-level overview of CARO, download our info brochure or visit the CARO website.

Development Status

The current application is a beta version, which is continuously being developed further.

If you are in the process of testing CARO, we would love to hear your feedback. Which functionalities or info screens are useful to you? What should we add or remove? How can we make your life easier? Please get in touch through one of the means detailed at the bottom of this page.

Getting Started

You must be invited to CARO before you can access the app's dedicated Service Provider space. The web app resides on api.caro.vc.

Once you have received an email invite, accept it by following the link in the email. On the CARO log-in screen you can check your details and set a password. After log-in, you will be forwarded to the CARO Dashboard.

You must be granted access by your VRS customers before you can facilitate VRS interactions on their behalf via our APIs.

Dashboard

The Dashboard provides your API authentication information and hyperlinks to VRS documentation. -->

System-wide Search

The search function applies across the CARO app. It groups results into applicable categories, such as reports, events, or credentials. You can access it from any app screen by finding it in the sidebar or using the keyboard shortcut CTRL+K.

Account Selection

Clicking on the account selector in the sidebar opens the account overview. All Service Provider Accounts to which you have been granted user access are listed here. You can switch between accounts by clicking on the switch option for each.

Customers

This screen shows a list of all customers who have granted you access to their account.

Customer Details

Clicking on any of the customers in the list will open a details view of this customer. Besides some basic information, it includes a list of their Enterprise Identifiers.

VRS Events

This screen shows a list of all VRS transactions executed under the same client ID, i.e. your Service Provider account. Each generation or verification event associated with any of your customers is listed here.

Note that CARO displays one Event status for incoming events and up to two statuses for outgoing events. This is similar to the view available to your customers. Find further explanations in the Trading Partner user guide.

Event Details

Clicking on any of the events in the list will open a details view of this transaction. Besides some basic information, this page provides you with a developer view of the sent or received event. For Outgoing Events (Generations), you will also see a section called Counterparty Interaction. The counterparty is the trading partner at the other end of the selected VRS-facilitated exchange and may or may not be another one of your customers.

Settings

You can manage the appearance of your company profile within CARO.

There is also a dedicated section showing your API authentication information, which is only visible to certain user types (see FAQ). The Client ID and Client Secret listed amongst your API authentication details are effectively your access credentials to CARO. You can use the same Client ID and Client Secret to communicate with CARO when acting on behalf of each of your customers. These details pertain to your service provider account, not your customers' accounts.

These authentication details do not change. You will use the same details for every interaction with CARO. However, you can rotate them yourself to increase system security, for example upon a suspected leak or in defined intervals.

If you are interested in referring CARO to others, you can find a custom link here too. Contact us to learn more about our referral program.

User Management

This screen shows all users who have access or have been invited to your Service Provider space.

Adding New Users

After clicking Invite New User on the main screen, you will be directed to a form to enter the new user's email address and select their user role. Once you have confirmed the invitation, the new user will receive an email inviting them to set up their access.

Available User Roles

Service Provider Manager

• Administration of Service Provider space
• User and role management

Service Provider Developer

• as Service Provider Manager + access to client ID and secret for authentication

Managing Existing Users

Clicking on any of the existing users on the main screen will open a details view of this user.

Clicking on your own user on the main screen or in the sidebar will open a details view of your own set-up. The display here is more expansive than for other users.

You can change the selected user's role and access by clicking on Edit Profile.

Activity Log

This screen lists the actions account users have performed in your Service Provider Account, such as client key rotation or profile updates.

Further Resources

• CARO API Documentation
• CARO VRS Testing Guide
• OCI Getting Started Guide

Trading Partner User Guide

CARO User Guide for Trading Partners

This document walks you through the functionalities of the CARO app, Spherity's Credentialing Service for Authorized Trading Partners (ATP), to enable you to navigate the user interface. It does neither explain any technical details of the Credentialing Service nor provide guidelines for the technical implementation of CARO.

This document will be updated continuously. Please check back frequently, as new features and functionalities will be added to the application and explained here.

If you are looking for a high-level overview of CARO, download our info brochure or visit the CARO website. You may also want to peruse some essential concepts about our app.

Development Status

The current application is a beta version, which is continuously being developed further.

If you are in the process of testing CARO, we would love to hear your feedback. Which functionalities or info screens are useful to you? What should we add or remove? How can we make your life easier? Please get in touch through one of the means detailed at the bottom of this page.

Getting Started

You must be invited to CARO before you can access it. The web app resides on api.caro.vc.

Once you have received an email invite, accept it by following the link in the email. On the CARO log-in screen you can check your details and set a password. After log-in, you will be forwarded to the CARO Dashboard.

If you are unsure, you may want to watch our short video that walks you through the onboarding process.

Dashboard

The dashboard provides some useful information about your credentials and account activity. It will also alert you to any critical issues that require your attention (see Attention required card in the screenshot below).

New to CARO?

When you get started with CARO, the dashboard will show you a Welcome card. Simply follow the steps explained on the card to get set up with your first two essential credentials. An Attention required card may pop up to keep you right in case of any critical issues along the way.

System-wide Search

The search function applies across the CARO app. It groups results into applicable categories, such as reports, events, or credentials. You can access it from any app screen by finding it in the sidebar or using the keyboard shortcut CTRL+K.

Account Selection

Clicking on the account selector in the sidebar opens the account overview. All Enterprise Accounts to which you have been granted user access are listed here. You can move between accounts by clicking on the switch option for each. You can also access purchase options for new Enterprise Accounts from here.

VRS Events

You can find your VRS Events in the menu section VRS Interactions. This screen shows a list of all VRS interactions with your Enterprise Account once they have taken place. You can filter your view and download transaction listings. The screen provides the status of incoming and outgoing VRS Events. Read more in section VRS Event Status below.

Before any interaction can happen, your VRS provider must have been granted restricted access to your Enterprise Account. This is either done by Spherity or your VRS provider in agreement with you.

VRS Event Details

Clicking on any of the interactions in the VRS Events list will open a details view of this event.

Example: Outgoing VRS Event

For Outgoing VRS Events only, you will see a section called Counterparty Interaction. The counterparty is the trading partner you have interacted with in the selected VRS-facilitated exchange. Read more in section VRS Event Status below.

VRS Event Status

In the list view, CARO displays one VRS Event status for incoming events and up to two statuses for outgoing events.

The first status icon in the VRS Events overview screen applies to both outgoing and incoming VRS Events. It tells you about the VRS-facilitated credential exchange at your end of the interaction with the other trading partner, i.e. your counterparty.

The second status icon in the VRS Events overview screen applies only to outgoing VRS Events. It tells you what has happened to your VRS-facilitated credential exchange at your counterparty's end of the interaction. This status is only available when your counterparty is also a CARO user. Furthermore, it is possible that your VRS finds that something is wrong with your credential and may choose not to send it over to your business partner. Hence, there would be no counterparty status.

Note that the second icon pops out when you hover over it in the VRS Events overview screen. The blue eye icon tells you that the second (i.e. counterparty) status is available. The eye is greyed out when the counterparty status is not available.

On drilling into VRS Event Details of an outgoing event, you will see a section called Counterparty Interaction. This section portrays the flow of your credential details from your CARO Enterprise Account through your VRS to the other trading partner.

If the counterparty status is available, the following flow is displayed.

If the counterparty status is not available, the following flow is displayed.

VRS Reports

You can find your VRS Reports in the menu section VRS Interactions. This screen shows a list of all VRS messaging roundtrips, i.e. the outgoing and incoming VRS Events belonging to the same unique interaction identifier (Correlation UUID). The same identifier is also used by your VRS provider and, thus, represents a shared reference for audits and inquiries across systems.

VRS Report Details

Clicking on any of the VRS roundtrips in the VRS Reports list will open a details view of this roundtrip. This tells you what exactly happened in the entire interaction trail between your Enterprise Account and your counterparty.

Clicking on any of the interactions in the Correlating Events list will redirect you to the VRS Event details view of this event.

Enterprise Identifiers

You can find your Enterprise Identifiers in the menu section Enterprise Wallet. This screen shows your Enterprise Account's decentralized identifiers (DIDs). Each Enterprise Account must have at least one such Enterprise Identifier because having a unique DID assigned to your enterprise is a prerequisite for credential acquisition. Each enterprise that requires its own set of credentials must have its own DID. This DID is persistent. This means it will never change within the system so that it continuously identifies the particular enterprise to which it had been assigned originally.

Enterprise Identifier Details

Clicking on any of the DIDs in the Enterprise Identifier list will open a details view of this DID.

Adding New Enterprise Identifiers

Generally, CARO automatically creates your first DID as part of the initial onboarding process.

Should you require more DIDs, say for additional business locations that hold their own credentials, you will need to create a new unique DID per additional enterprise.

After clicking Create New Identifier on the main screen, you will be prompted to give your new DID a meaningful name and select a method to create this identifier, a so-called DID method. If all you want is to create a DID for a real enterprise, simply select the first option (did:ethr). If you are interested in experimenting with CARO, select any of the other DID methods. Please contact us if you want us to join your experiment or to discuss your needs.

Once you have confirmed your choice, you will be redirected to the Enterprise Identifiers overview page where you can see your newly created DID listed.

Credentials

On joining CARO you will undergo a process called credentialing during which your enterprise's legal and regulatory status within the US pharmaceutical supply chain is checked. The result of this process are the digital Verifiable Credentials you hold within CARO.

You can find your Credentials in the menu section Enterprise Wallet. This screen shows these Verifiable Credentials associated with your Enterprise Account. You can drill into the detail of credentials you already hold and check the status of any credential requests that are awaiting issuance.

Credential Details

Clicking on any of the credentials in the list will open a details view of this credential.

Adding New Credentials

Step 1. After clicking Acquire New Credentials on the main screen, you will be prompted to select the Enterprise Identifier underlying the new credential.

If you only have one Enterprise Identifier...

• and your new credential is to be held by the same legal entity
• and you want to manage that entity's data within the same CARO Enterprise Account,

then simply select the existing identifier.

If you are looking to obtain a credential for a different legal entity whose data you want to manage within the same CARO Enterprise Account, you would need to obtain an additional Enterprise Identifier first. Find out how to create a new Enterprise Identifier in section Adding New Enterprise Identifiers before acquiring a new credential.

If you are looking to obtain a credential for a different legal entity whose data you want to manage in a separate CARO Enterprise Account, please contact your solution provider's customer support team or us directly.

Step 2. Next select the desired Credential Type, i.e. what kind of credential you need. Note that you can only acquire a DSCSA ATP Credential after obtaining an Identity Credential.

Step 3. Next select the Credential Issuer. This is the organization that will perform the due diligence on the pieces of evidence you will provide as justification for your credential request. When they are satisfied that everything is in order, they will issue the credential straight into your CARO Enterprise Account.

Once you have confirmed your choice, you will be redirected to the user interface of the integrated Credential Issuer. There you will need to provide the requested details for the issuer's due diligence process such as the registered company address and certain documents. Find out what's needed in our preparation guide.

Watch this short video to get an idea of the issuer's interface.

Credential Request Progress

Clicking on any of the pending credential requests on the main screen in the credentials list will open a details view of this credential request. Here you can see how far the request has already progressed through the application stages. Your current status is the actual status. Future stages are predicted based on expected next steps. The actual status is revised automatically as soon as the integrated Credential Issuer sends updates to CARO.

You can resume incomplete credential requests from this screen, too. Clicking the button will redirect you to the Credential Issuer interface.

When there is a comment from the Credential Issuer, you can reveal it by hovering over the little speech bubble icon.

Trading Partners

This screen shows a list of all authorized trading partners with whom interactions have taken place. This view auto-populates. You do not need to add your trading partners manually.

Trading Partner Details

Clicking on any of the trading partners in the list will open a details view of this trading partner. Besides general company information, this includes a list of all VRS-facilitated roundtrips between them and you. Drilling into the detail of an exchange will redirect you to the respective detailed VRS Report.

Settings

Security Settings

Here you manage the security settings that apply across the entire Enterprise Account.

Billing & Plans

This screen shows details related to your subscription and links out to the Stripe customer portal where you can find more information and manage your subscription as well as customer details.

Service Providers

This screen lists all the service providers that are connected to your Enterprise Account.

User Management

This screen shows all users who have access or have been invited to the selected Enterprise Account.

Adding New Users

After clicking Invite New User on the main screen, you will be directed to a form to enter the new user's email address and select their user role. Once you have confirmed the invitation, the new user will receive an email inviting them to set-up their account access.

Available User Roles

Admin

• Administrating wallet set-up
• Enterprise identity configuration
• User and role management
• Credential management

Credential Manager

• Requesting Identity and ATP credentials
• Managing existing credentials

Auditor

• Monitoring VRS events
• Investigating VRS events

Managing Existing Users

Clicking on any of the existing users on the main screen will open a details view of this user.

Clicking on your own user on the main screen or in the sidebar will open a details view of your own set-up. The display here is more expansive than for other users.

You can change the selected user's role and access by clicking on Edit Profile.

Activity Log

This screen lists the actions account users have performed in your Enterprise Account, such as applying for a credential or removing another user.

Credential Issuer User Guide

CARO User Guide for Credential Issuers

This document walks you through the functionalities of the CARO app, Spherity's Credentialing Service for Authorized Trading Partners (ATP), to enable you to navigate the user interface. It does neither explain any technical details of the Credentialing Service nor provide guidelines for the technical implementation of CARO. Please refer to our API Specifications for technical guidance.

This document will be updated continuously. Please check back frequently, as new features and functionalities will be added to the application and explained here.

If you are looking for a high-level overview of CARO, download our info brochure or visit the CARO website. You may also want to peruse some essential concepts about our app.

Development Status

The current application is a beta version, which is continuously being developed further.

If you are in the process of testing CARO, we would love to hear your feedback. Which functionalities or info screens are useful to you? What should we add or remove? How can we make your life easier? Please get in touch through one of the means detailed at the bottom of this page.

System-wide Search

The search function applies across the CARO app. It groups results into applicable categories, such as reports, events, or credentials. You can access it from any app screen by finding it in the sidebar or using the keyboard shortcut CTRL+K.

Account Selection

Clicking on the account selector in the sidebar opens the account overview. All Service Provider Accounts to which you have been granted user access are listed here. You can switch between accounts by clicking on the switch option for each.

Customers

This screen shows a list of all customers who have granted you access to their account.

Customer Details

Clicking on any of the customers in the list will open a details view of this customer. Besides some basic information, it includes a list of their Enterprise Identifiers.

Credentials

Issued Credentials

This screen shows a list of all Verifiable Credentials you have issued.

Credential Details

Clicking on any of the credentials in the list will open a details view of this credential. You will also be able to manage the revocation of the selected credential here. Find out more about our Ethereum-based revocation method in our blog article.

Onboardings

This screen shows a list of all onboardings.

CARO manages credential requests through so-called onboardings. One onboarding is effectively mapped to the lifecycle of one Verifiable Credential. For example, a credential may need to be re-issued after expiry. Both steps, initial and subsequent issuance would be mapped against the same onboarding ID.

Onboarding Progress

Clicking on any of the onboardings in the list will open a details view showing the progress of the credential request.

Settings

You can manage the appearance of your company profile within CARO.

There is also a dedicated section showing your API authentication information, which is only visible to certain user types (see FAQ). The Client ID and Client Secret listed amongst your API authentication details are effectively your access credentials to CARO. You can use the same Client ID and Client Secret to communicate with CARO when acting on behalf of each of your customers. These details pertain to your service provider account, not your customers' accounts.

These authentication details do not change. You will use the same details for every interaction with CARO. However, you can rotate them yourself to increase system security, for example upon a suspected leak or in defined intervals.

If you are interested in referring CARO to others, you can find a custom link here too. Contact us to learn more about our referral program.

User Management

This screen shows all users who have access or have been invited to your Service Provider space.

Adding New Users

After clicking Invite New User on the main screen, you will be directed to a form to enter the new user's email address and select their user role. Once you have confirmed the invitation, the new user will receive an email inviting them to set up their access.

Available User Roles

Service Provider Manager

• Administration of Service Provider space
• User and role management

Service Provider Developer

• as Service Provider Manager + access to client ID and secret for authentication

Managing Existing Users

Clicking on any of the existing users on the main screen will open a details view of this user.

Clicking on your own user on the main screen or in the sidebar will open a details view of your own set-up. The display here is more expansive than for other users.

You can change the selected user's role and access by clicking on Edit Profile.

Whitelist Guide

Why would I need to whitelist?

CARO is a web-based app. If CARO does not work, for example you cannot access the onboarding page, then it may be that your IT system does not permit access to certain [URLs][u] that CARO requires. These URLs need to be whitelisted (allowed) by your IT system for CARO to be fully functional.

In addition, your email provider may block CARO’s service emails. This would result in you not receiving app notifications or invites to get started with CARO or join other accounts.

CARO not working properly?

Please troubleshoot the issue as follows with your own IT team:

1. Is there a proxy server configured on your computer?
2. If there is a proxy server configured, please verify the following [domains][u] are allowed:

Spherity-managed

Legisym-managed (integrated credential issuer)

The following sites are owned by Legisym, LLC and are used during the credentialing process with Spherity Inc. The sites allow the user to provide data to Legisym for due diligence. Legisym reviews the data to determine if credentials can be issued.

3. To check that all required domains have been whitelisted, please try to open them.
4. If any domain is still blocked, please follow your internal process to unblock it.

CARO emails not arriving in your inbox?

First of all, please check your spam folder.

If there are no CARO emails to be found anywhere in your mailbox, add [email protected] to your trusted email address list. Ask your IT team if needed.

Support & Feedback

Email

Please contact [email protected] for product-related questions or feedback, or [email protected] for technical queries.

Interactive chat

Inside the CARO app you'll find a chat bubble symbol. Use this to report bugs or start a conversation with us straight from wherever you are in the app. You can also reach this message tool from outside of the CARO app at help.caro.vc.

Slack for integrators

We offer a dedicated Spherity Slack support channel to our integrators. Seeking assistance or offering feedback there will be one of the most straight-forward ways for you to reach the CARO team.

App Status Monitor

The app status, including maintenance updates, can be found at https://status.caro.vc/.

You can also subscribe to updates via RSS: https://status.caro.vc/rss.