View Categories

VRS Provider API Integration

Table of Contents

Introduction #

The Verification Router Service (VRS) is a network designed to pass verification requests between trading partners in the pharmaceutical supply chain in order to meet the requirements of the U.S. Drug Supply Chain Security Act (DSCSA).

As a vendor-driven network, the VRS has traditionally relied on certificate exchanges and whitelisting between solution providers. More recently, verifiable credentials have introduced to provide an additional layer of authentication, allowing responders (e.g. manufacturers and repackagers) to be certain that requestors (e.g. wholesalers and dispensers) are Authorized Trading Partners (ATPs) under the law.

Authentication #

In order to access LedgerDomain’s APIs, secure authentication is required. XATP currently supports two authentication methods: (1) JWT authentication token and (2) API key.

The JWT authentication token method is recommended for all VRS providers. This method allows for each VRS solution provider to consolidate all of their customers under a single client ID and client secret. Customers have the ability to select their VRS provider of choice, and delegate access to their credential to a VRS provider organization provisioned on XATP. The API key method is available for general testing, including the use of happy path and sad path test scripts.

This document exclusively covers the JWT authentication token method. For information about the API key method, see our Stoplight documentation here.

VRS Integration Workflow #

As part of the integration between VRS providers and ATP credentials, XATP by LedgerDomain provides a web-based dashboard for trading partners to manage their credentials. VRS providers access XATP functionality in the following way:

  • Step 1. The trading partner designates the VRS provider as being able to make use of their credential for verifying and signing operations. LedgerDomain communicates the decentralized identifier (DID) used by the trading partner.
  • Step 2. Using the client ID and client secret provided to them by LedgerDomain, the VRS provider generates a JWT bearer token.
  • Step 3. Using the bearer token, and specifying their particular customer’s DID, the VRS provider accesses the XATP VP Generate and VP Verify API endpoints as outlined in the OCI Conformance Criteria. This allows the VRS provider to check inbound Verifiable Presentations (VPs) of credentials via the VRS, and to generate new VPs to append to VRS messages.

Environments #

LedgerDomain provides two environments for VRS providers:

  • Sandbox for testing and validation: https://api-sandbox.xatp.io/
  • Production for real life: https://api.xatp.io/

Note: DIDs in the sandbox environment effectively represents a specific (imaginary) trading partner within the system. As these DIDs have been made available only for testing purposes, they have not been issued by our integrated Credential Issuer, as this is not required for API endpoint testing and ensures that production-grade credentials are not inadvertently exposed during testing.

API Endpoints #

LedgerDomain provides three API endpoints to VRS providers. More information about these endpoints can be found in the OCI conformance criteria and the linked API documentation.

Bearer Token Generation #

{{base-URL}}/v2/user/partner/auth

This endpoint allows you to generate a bearer token, which can subsequently be used in the authentication headers of the other two API requests. Full documentation including samples is available here.

Request #

  • audience – Always set to ledgerdomain.
  • client_id – The client ID is supplied to you by LedgerDomain and identifies your organization; you may have multiple client IDs.
  • client_secret – The client secret is supplied to you by LedgerDomain.
  • grant_type – Always set to client_credentials.

Response #

The response includes the access_token in the form of a string, which you can use for authentication. It also includes a $schema reference, an expires_in field (always 86400, i.e. 24 hours), and a token_type (always Bearer)

Generate a VP #

{{base-URL}}/oci-dwp/api/v1/verifiablePresentation/generate

This endpoint allows you to generate a VP of a credential. Full documentation including samples is available here; be sure to use the bearer token in the authentication header as shown.

Request #

Optional query parameters can be appended to the URL of the request:

  • vc-credentialStatus – Whether or not to check the credentialStatus of the requested Credential (revoked or non-revoked).
  • vc-expirationDate – Whether or not to check the expirationDate of the requested Credential.
  • vc-issuanceDate – Whether or not to check the issuanceDate of the requested Credential.
  • vc-proof – Whether or not to check the proof of the requested Credential.

Required fields:

  • corrUUID – The correlation uuid of the product identifier verification message.
  • credentialType – The type of credential being requested (can be DSCSAATPCredential for trading partners and DSCSAAuthorityCredential for regulators).
  • holderDID – The DID of the trading partner that requests a verification of the provided Verifiable Presentation.

Optional fields:

  • __ignoreIat – When set to true, ignore the standard expiration time for VPs. Made available for test purposes, and for later auditability.
  • __trustedIssuers – Used for internal testing purposes on non-production environments.
  • __usePubInt – Used for internal testing purposes on non-production environments.

Response #

A response code of 2XX indicates the request was successfully received, understood, and accepted. A response code of 4XX indicates the request contains bad syntax or cannot be fulfilled. A response code of 5XX indicates the server failed to fulfill an apparently valid request.

All 2XX responses include:

  • success – if the VP Generate request was successful, this will appear as true. If it failed, this will appear as false.

If the VP Generate request was successful, the response will include:

  • verifiablePresentation – The JWT formatted and base64 encoded Verifiable Presentation.
  • holderDID – The DID that holds the requested credential.
  • corrUUID – The correlation UUID of the product identifier verification message.
  • credentialType – The type of credential that has been generated (can be DSCSAATPCredential for trading partners and DSCSAAuthorityCredential for regulators).
  • message – An additional message that may provide further context.

If the VP Generate request failed, the response will include:

  • $schema – A link to the error model
  • title – The title of the error (e.g. Forbidden)
  • status – The relevant HTTP error code (e.g. 403)
  • errors – An array of errors encountered, including human-readable message as well as the location of the error and the value causing the error.
  • detail – a human-readable error message (e.g. "validation failed")

If the VP Generate request failed due to an error covered under the OCI conformance criteria, the response will include an errorCodes array that includes a list of error code(s) specified here.

Verify a VP #

{{base-URL}}/oci-dwp/api/v1/verifiablePresentation/verify

This endpoint allows you to verify a given VP. Full documentation including samples is available here; be sure to use the bearer token in the authentication header as shown.

Request #

Required fields:

  • verifiablePresentation – The verifiable presentation (JWT presentation) to verify, provided in JWT Base64 encoded format.
  • verifierDID – The DID of the trading partner that requests a verification of the provided Verifiable Presentation.

Optional fields:

  • __ignoreIat – When set to true, ignore the standard expiration time for VPs. Made available for test purposes, and for later auditability.
  • __trustedIssuers – Used for internal testing purposes on non-production environments.
  • __usePubInt – Used for internal testing purposes on non-production environments.

Response #

A response code of 2XX indicates the request was successfully received, understood, and accepted. A response code of 4XX indicates the request contains bad syntax or cannot be fulfilled. A response code of 5XX indicates the server failed to fulfill an apparently valid request.

All 2XX responses include:

  • success – if the VP has passed the check, this will appear as true. If it failed, this will appear as false.

if the VP has passed the check, the response will include:

  • verifiablePresentation – The VP that has been verified.
  • verifierDID – The DID of the trading partner that was used to verify the VP.
  • message – An additional message that may provide further context.

if the VP has failed the check, the response will include:

  • $schema – A link to the error model
  • title – The title of the error (e.g. Forbidden)
  • status – The relevant HTTP error code (e.g. 403)
  • detail – a human-readable error message (e.g. "organization does not have permission to issue or verify this VP")

If the VP Verify request failed due to an error covered under the OCI conformance criteria, the response will include an errorCodes array that includes a list of error code(s) specified here.

Postman Resource #

To better support VRS providers integrating with LedgerDomain, we typically provide Postman collections packaged with documentation. The Postman collections include everything you need to run a full end-to-end workflow, including test client IDs and test client secrets, as well as a number of variables. In some cases, these variables will automatically update for your convenience (e.g. a random UUID is automatically created for each VP Generate event, and a VP Verify call will automatically draw from the most recent VP generated).

To get the most recent version of our VRS provider Postman collection, contact integrations@ledgerdomain.com.

Using the Collection #

  • Step 1: Run “VRS Provider XATP Token” to generate a bearer token. The token expires after 24 hours.
  • Step 2: Run the “VP Generate” request to create a VP. This simulates a requestor establishing their ATP status.
  • Step 3: Run the “VP Verify” request to create a VP. This simulates a requestor checking the inbound VP.

Unpacking a VP #

VPs are encoded in Base64, and can be readily decoded. Note that decoding a VP is not sufficient to check its validity, as this includes a range of other checks (e.g. schema validation, signatures, trusted issuer registry, revocation checks, etc.)

Resources #