OpenAPI Specification

This page introduces the VDP API, using the OpenAPI Specification, and importing it into Postman

API Documentation

The VDP API is documented with an Open API Specification (OAS) available at:

OAS Authentication

Network requests can be made directly from the OpenAPI Specification. As a prerequisite, you must create a Machine to Machine Application, as described here.

Go to "Authentication" on the top of the OpenAPI Specification page.

Copy your Application's client id and client secret into the client credentials flow section, then click "Get Token".

The browser client now has an access token which can be used to make API network requests.

Making OAS Network Requests

The OpenAPI Specification describes all the available endpoints with textual descriptions, schemas and examples. This guide is not intended to repeat that level of documentation. Rather, we will make a sample network request to show how that can be done throughout the OpenAPI Specification.

For example, go to the credential issuance endpoint and click "Try".

This will make a network request to the VDP API.

The response will most likely be an error such as the one shown below.

In this case, the DID in the example is not one that the organization is controlling. If you replace it with one of your VDP Organization's DIDs, the issuance should succeed.

Required Scopes

Another possible reason to be getting an error response is that the authorized application has not been granted the necessary scope to make the specific endpoint request.

Hover over the lock icon on the top right to see the required scope for invoking a particular endpoint. In this case, create:credential is required to call the credential issuance endpoint.

See the guide on Application Creation for more about selecting scopes for your application.

Postman OAS Import

Another common use of OpenAPI Specifications is importing into Postman. Postman provides a simple environment to get started with the VDP API, and also provides a powerful set of features for scripting, automating, testing, etc.

Note that in addition to importing the "raw" OAS into Postman, a dedicated "getting started" Postman collection is also available on the next page of the guide which will get you quickly up and running with your Postman development.

In Postman, go to File -> Import.

You can continue building your application by importing the VDP Open API Specification. First go to File -> Import. Then click on the "Link Tab".

In the text field enter, And then click on the "Continue" button.

Once you click on the Continue button, you will be shown a screen to confirm importing the API.

From the OpenAPI specification will be imported as a collection.

You can now drag in any of the imported VDP OAS endpoints to your “Getting Started” collection and continue building your application. Make sure that your network requests’ base URL variable name corresponds to the collection ({{API_BASE_URL}}) and that they are properly authorized (“Inherit auth from parent”).

Happy coding!

Last updated