VRS Endpoints

As the name suggests, these endpoints are for VRS providers offering a seamless way to exchange and verify credentials

Authentication Please see Authentication for a detailed description of how to authenticate yourself with our API.

POST/api/v1/verifiablePresentation/generate

Generating a Verifiable Presentation

The VP generation API generates a Verifiable Presentation of the requested ATP Credential in JWT format for usage in ATP Credential exchange.

Optional query parameters

During the generation of a Verifiable Presentation none of requested credential fields are checked for validity by default. This is done on purpose to save on processing time in generation use cases, as all fields will always be validated by a verifing side via the /api/v1/verifiablePresentation/verify endpoint. You may optionally enable these checks via parameters. E.g /verifiablePresentation/generate?vc-proof=false&vc-issuanceDate=false

Name
vc-expirationDate
Type
boolean
Description
Whether or not to check the expirationDate of the requested Credential
Name
vc-proof
Type
boolean
Description
Whether or not to check the proof of the requested Credential
Name
vc-issuanceDate
Type
boolean
Description
Whether or not to check the issuance date of the requested Credential
Name
vc-credentialStatus
Type
boolean
Description
Whether or not to check the credential status of the requested Credential (revoked or non-revoked)

Required attributes

Name
corrUUID
Type
string
Description
Correlation UUIDv4 which identifies a VRS request-response pair across networks.
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 randomly generated corrUUID that you have received from the requester instead of creating a new random corrUUID. The requester's corrUUID can be extracted from the decoded received Verifiable Presentation.
Name
holderDID
Type
string
Description
The DID of the customer who holds the requested DSCSA ATP Credential
The customer you are serving VRS Events for will either share their DID with you via traditional communication formats or you can view a list of Identifiers in your web frontend after the customer has invited you to their Enterprise Account.
Name
credentialType
Type
enum/string
Description
Type of the Credential (IdentityCredential OR DSCSAATPCredential OR DSCSAAuthorityCredential OR DSCSAATPEquivalentCredential) While four values are allowed here, most VRS Events will use DSCSAATPCredential.

Request

POST

https://api.caro.vc/api/v1/verifiablePresentation/generate

curl -G "https://api.caro.vc/api/v1/verifiablePresentation/generate" \
  -H "Authorization: Bearer {token}" \
  -d corrUUID="5b58c147-1afb-43c1-81fe-84b9394a1e50"
  -d holderDID="did:ethr:ropsten:0x022e41cff8e1d8c34f82397312490f96379cac8027696d8774f3eef72551691def"
  -d credentialType="IdentityCredential"

Response

  {
    "success": true,
    "verifiablePresentation": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImRpZDpleGFtcGxlOmFiZmUxM2Y3MTIxMjA0[...]",
    "holderDID": "did:ethr:example",
    "corrUUID": "5b58c147-1afb-43c1-81fe-84b9394a1e50",
    "credentialType": "DSCSAATPCredential",
    "message": "Generation succeeded"
  }

Response Description

Response Field	Description
`success`	Boolean value indicating whether or not the request was successful.
`verifiablePresentation`	The JWT formatted and base64 encoded Verifiable Presentation.
`holderDID`	The holderDID that was used to generate the Verifiable Presentation.
`corrUUID`	The corrUUID that was used to generate the Verifiable Presentation.
`credentialType`	The credentialType that was used to generate the verifiable presentation.
`message`	Additional message to be included for humans and/or logging systems

Error Response

{
  "success": false,
  "errors": [
    "Generation of Verifiable Presentation failed because Credential has been revoked"
  ],
  "errorCodes": [
    "vc_revoked",
    "vc_proof_invalid"
  ]
}

Fields

Response Field	Description
`success`	Boolean value indicating whether or not the requested was successful.
`errors`	a list of error messages describing the error code(s) encountered while attempting to generate VP
`errorCodes`	a list of error code(s) as specified in the Digital Wallet Conformance Criteria encountered while attempting to generate VP

POST/api/v1/verifiablePresentation/verify

Verifiable presentation verification

The VP verification API validates a Verifiable Presentation of an ATP Credential in JWT format created by the VP generation API.

Required attributes

Name
verifiablePresentation
Type
base64/string
Description
The JWT-formatted and base64-encoded Verifiable Presentation.
Name
verifierDID
Type
string
Description
The DID belonging to the entity verifying the incoming Verifiable Presentation.

Refer to our VRS FAQ to understand how to extract details from the Verifiable Presentation.

Request

POST

https://api.caro.vc/api/v1/verifiablePresentation/verify

curl -G "https://api.caro.vc/api/v1/verifiablePresentation/verify" \
  -H "Authorization: Bearer {token}" \
  -d verifiablePresentation=""
  -d verifierDID=""

{
  "success": true,
  "verifiablePresentation": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImRpZDpleGFtcGxlOmFiZmUxM2Y3MTIxMjA0[...]",
  "message": "Verification succeeded"
}

Response Description

Field	Description
`success`	Boolean value indicating whether or not the request was successful.
`verifiablePresentation`	The JWT formatted and base64 encoded Verifiable Presentation.
`message`	Additional message to be included for humans and/or logging systems

Error Response

{
  "success": false,
  "errors": [
    "expirationTime check failed",
    "issuanceDate check failed"
  ],
  "errorCodes": [
    "vc_exp_expired",
    "vp_iat_expired"
  ]
}

Error Fields

Field	Description
`success`	Boolean value indicating whether or not the request was successful.
`errors`	a list of error messages describing the error code(s) encountered while attempting to verify a VP
`errorCodes`	a list of error code(s) as specified in the Digital Wallet Conformance Criteria encountered while attempting to verify a VP

POST /api/v1/serviceProviders/tenants

Create Tenant

Restricted Feature This feature is only available for specifically authorized service providers. Please contact us if you require this functionality.

The Create Tenant API creates a new Authorized Trading Partner Enterprise Account in CARO with the provided information in the request body of the endpoint call.

Required attributes

Name
name
Type
string
Description
Name of the enterprise
The name should be the legal name of the trading partner company you serve as a VRS provider.
Name
initialUser
Type
string
Description
Email address of the initial user who will manage this Enterprise Account
The initial user must be someone in a managerial role within the trading partner company.

Request

GET

https://api.caro.vc/api/v1/serviceProviders/tenants

curl https://api.caro.vc/api/v1/serviceProviders/tenants \
  -H "Authorization: Bearer {token}"
  -H 'Content-Type: application/json' \
  --data-raw '{
      "name": "Some Pharma Company",
      "initialUser": "[email protected]"
    }'

Response

{
  "id": "79806b8f-f4d4-474b-a069-657c3eb8aae9",
  "createdAt": "2022-06-01T10:05:51.004Z",
  "updatedAt": "2022-06-01T10:05:51.004Z",
  "slug": "some-pharma-t-162b",
  "name": "Some Pharma Company",
  "webUrl": "",
  "demo": "NONE"
}