VRS FAQ
The FAQ here are intended for CARO integrators and service providers who have already had some exposure to CARO. If you have just discovered CARO, you might find the introductory resources on our website helpful to get started.
CARO usage
For how long are authentication tokens valid?
You can use the same Client ID and Client Secret to communicate with CARO when acting on behalf of each of your VRS customers. The authentication tokens have a validity of 24 h. Please reuse each token until its expiry. Your maximum daily usage allowance is 150 tokens in the absence of any further arrangements with us. This is also highlighted in the VRS guide.
If the use of one client Secret:ID pair or one authentication token for all your VRS customers conflicts with your own architecture, do let us know, since we have no insights into your systems. In that case, we may need to reconsider certain design decisions at our end.
Why can I not see the client authentication details?
The Client ID and Client Secret can be found under Settings.Only users set up as Service Provider Developers are permitted to see this information. Ask a team member with that access permission to upgrade your role in User Management in the Service Provider section.
What you should see...
What kind of results does the CARO search function return?
Our search currently returns fuzzy results. So, if you look for a specific corrUUID or DID, make sure to check the returned result, as the search may have found something that is highly similar if there is no exact match.
VRS set-up
How do I connect a VRS customer in my system to CARO?
While we cannot provide any advice specifically for your system, a key task you need to perform is to link the customer identifiers between our two systems. Your customer's unique identifier related to CARO is their Enterprise Identifier. You can find it in the Customers section of your CARO Service Provider Account (see VRS guide). You will need to map this identifier to the GLN your customer wants to use for VRS-facilitated interactions. If applicable, you may also want to connect the CARO Enterprise Identifier to another customer ID used in your system.CARO will send you two notifications in the customer onboarding process:
- The connection notification tells you that your CARO Service Provider account has been connected to the Trading Partner's CARO Enterprise Account.
- The routing readiness notification tells you that your customer has successfully passed due diligence checks from the Credential Issuer and, thus, obtained the ATP credential that your VRS fetches for routing.
How do I need to handle the corrUUID in a VRS response?
The purpose of the corrUUID is to connect all events in a full VRS roundtrip (request and response) for a consistent audit trail. Hence, as a responder you must re-use the corrUUID that you have received from the requester instead of creating a new random corrUUID. The requester’s corrUUID can be extracted from the nonce field in the decoded received Verifiable Presentation.Please peruse our VRS guide as a refresher.
The relevant OCI references in the Digital Wallet Conformance Criteria are:
How can I retrieve details from a received Verifiable Presentation?
The Verifiable Presentation is in a JWT format and base64-encoded. Decode it from base64 and you will have a familiar JWT structure. The “vp” root-level field contains the presentation. You can trial decoding a VP or JWT using the decoder at https://jwt.io/.Can I change the tenant email invite?
This question assumes that you use our Create Tenant API. When a new Trading Partner tenant (CARO account) is created, you can only invite 1 person/email address and this cannot be changed. We suggest 2 options if this person ends up not being the one who will handle the credentialing in CARO:- You ask the wrongly invited person to accept the invite and then invite their appropriate colleague as Admin via User Management. The second person may then remove the first user if so desired.
- You ask the wrongly invited person to ignore the invite or, if too late, not start with the credentialing steps in CARO. You create a new account and invite the correct user. The new account can have the same name as the first one, as they all get a unique tag in the background. If this concerns a PROD account, please also let us know which account is the wrong one, so we'll remove it, and you won't be billed for it.
I want to run a load test with CARO. What do I need to consider?
First, evaluate whether the standardized OCI VRS performance test suite is a suitable approach.If you choose to create and execute your own load test set-up on CARO's APIs, consider the following guidelines in order to produce comparable and meaningful results.
Handling authentication in high-volume requests
Making sure you are familiar with our authentication guide is important for normal operations of our connected services and particularly relevant in the context of load tests involving a high volume of requests.
Please see Authentication for a detailed description of how to authenticate yourself with our API.
Additionally, please be reminded that your client ID has a daily limit of 150 tokens you may generate in the absence of any further arrangements with us (see also our FAQ. Take this into consideration when executing load testing scripts that generate tokens on each execution.
We recommend that you implement dedicated logic in your load tests to check if a token is still valid and only generate a new one if it is expired at the start of your load test execution.
It is important to ensure that a token does not expire during the execution of your load test.
Errors and retries on generations and verifications of VPs
Should you encounter any non-200 class response codes on the generation or verification of Verifiable Presentations (VP), we recommend the following actions based on the response code:
- 100-199: Not to be expected. Please contact us if you encounter these response codes.
- 200-299: Success. No action required. Continue with test.
- 300-399: Not to be expected. Please contact us if you encounter these response codes.
- 400-499: Indicates a client error (e.g. invalid input or, in most cases, an expired token). Abort test on any of these errors.
- Check if your Bearer token is still valid. If not, generate a new one.
- Check if your input data (especially on the verification of a VP) is handled correctly. This often indicates that a previous generation failed and the error was not handled.
- If you believe your token and data are valid, contact us.
- 500-599: Indicates an unexpected server error. Abort test on any of these errors. Contact us.
General considerations for generations and verifications of VPs
For comparable results across load tests, we also recommend implementing the following measures:
- Always generate new correlation UUIDs for each generation of a VP. Do not reuse UUIDs. Our APIs will not error on duplicate UUIDs, but this will lead to a skewed result, as our database will handle load and creation of results differently.
- Follow the intended flow of the API:
- Create a generation request.
- Wait for the generation to finish.
- Check for any unexpected errors (see above).
- Create a verification request with the data from the generation.
- Wait for the verification to finish.
- Repeat.
Trading Partner FAQ
The FAQ here are intended for CARO users and people who have already had some exposure to CARO. If you have just discovered CARO, you might find the introductory resources on our website helpful to get started.
CARO usage
Which entity should we use for credentialing?
If your enterprise consists of more than one entity, you will need to choose one that is to represent the corporate ATP status. However, we cannot advise on the choice of entity for ATP credentialing.In the end, your compliance team must be comfortable with the following decisions:
- with which corporate identity you appear in VRS interactions and
- to which entities you give permission to utilize that corporate identity.
A way of thinking about this is to start at the end of the process: For which entity can you prove ATP status? Then this entity will also need to undergo identity proofing bearing in mind that:
- the entity name and address across all documents must match;
- the individual(s) submitting the evidence for due diligence must be authorized (usually employed) by the entity.
Your VRS set-up may also help you decide, as it makes sense to use the same entity for credentialing as you use with your VRS.
I have my first set of credentials! How does credential renewal work?
As far as regular renewals of your Identity and ATP credentials are concerned, your work is done.For as long as you maintain your contract and subscription payments with us, your credentials will be monitored and re-issued in the background. We will only need to involve you in further due diligence activities if something changes about your company that affects the validity of the credentials. If we detect anything like that, you will hear from us.
Do I have to upload all my trading partners to set up CARO?
No, you do not need to pre-populate CARO with your business partners. The list of trading partners within CARO will grow organically as interactions with your CARO Enterprise Account happen. The use of verifiable credentials by CARO caters for the underlying due diligence and capturing of salient counterparty details in your audit log by design.Are a Trading Partner's licenses visible in the electronic credentials?
No. Any organizational or licensing documents submitted during the credential application process are used for due diligence by the Credential Issuer but will not be disclosed in the electronic credentials.
What details are captured by CARO's audit log?
CARO offers two audit logs. One captures transaction details, such as transaction ID, time, type, status, interacting parties. The other one captures user activity, so you always know who did what when. These data are securely stored in a non-public AWS database.
What data are stored on the blockchain?
CARO stores an enterprise's unique Decentralized Identifier (DID) on the Ethereum blockchain. The DID leads to the DID document, which may contain details on how to contact you through your CARO account (a so-called endpoint). This enables certain types of information exchange with your trading partners for a variety of business interactions.
Why can I not access a page in the CARO app?
Certain web addresses might need to be whitelisted (allowed) by your IT system for CARO to be fully functional. Please refer to our whitelisting guide for more details.
CARO and my service provider
Is CARO interoperable with other digital wallets and service providers?
In short, yes as far as it is within our control.CARO is fully aligned with OCI’s Conformance Criteria for Digital Wallets. We are interoperable with any other digital wallet that is also aligned with these criteria. This means us and them can process each other’s credentials. We cannot guarantee interoperability with digital wallets that are not OCI-aligned.
Further, there are a number of service providers that offer message routing (VRS) and are fully integrated with CARO (see our website). This means they can use CARO to facilitate product enquiries on your behalf. These VRS have their own interoperability tests to make sure they can exchange information with each other.
How do I connect my VRS to my account?
The CARO team will do this for you once you give us the go-ahead or when your Service Provider requests a CARO account on your behalf (via API).
How do I remove my VRS provider’s account access?
The CARO team will do this for you if we are instructed to do so. Once deactivated, the VRS will no longer be able to generate or verify DSCSA ATP Credential presentations on your behalf.