Machine to Machine Applications

Applications enable access to VDP resources through the API. Applications are limited to a bound set of scopes, and enable 0Auth 2.0 access token grants through the Client Credentials flow.

Machine to machine Applications are used for running Verifiable Data Platform process automation and systems integration. Common usage includes:

• All API interaction

• VDP Adapters

• Postman scripts

• Systems integration and process automation

Once created, an Application can grant access tokens through the OAuth 2.0 Client Credentials authentication flow. The access token allows access to the VDP API, limited by the scopes defined on the Application.

Application Creation

From the Integrations navigation pane menu, select Applications.

Create a new Application.

Click New Application.

Application Metadata

Application metadata and scopes selection.

On the New Application page, enter a suitable Name and Description. As your Organization can have multiple Applications, it is important that they can be clearly told apart; the Name and Description should make it clear what the Application will be used for.

Name and Description can be edited later.

Application Scopes

Scopes are used to manage which API resources the Application will be permitted to access. As a general security rule, you should aim to minimize the amount of scopes for your Applications, narrowing permissions according to the tasks to be performed.

Note that scopes can only be selected during Application creation. Once created, scopes are fixed. If you need to change the scopes, you must create a new Application.

Click the Create Application button to finish.

Capture Client Credentials

Capture Application's Client Credentials.

Once the Application is created, you will be presented with its OAuth 2.0 Client Credentials.

As a security best practice, these are only presented this one time, so please take care to capture and store them accordingly.

Important!

Client Credentials should be kept secretly! Treat them with the same level of secrecy as you would treat your platform user password.

For convenience, the Client Credentials are available in several ways:

• As the "raw" client id and client secret. You can use the copy-icons for copying these individually.

• As a downloadable .env environment file, which also includes a full set of API variables.

• As a downloadable Postman environment file, which can be imported directly into Postman.

Obtaining Access Tokens

Access token grants are request on the endpoint documented here on the VDP OpenAPI Specification. Using the Client Credential CLIENT_ID and CLIENT_SECRET you can now authenticate to obtain an access token with POST /oauth/token:

curl --location --request POST 'https://platform.transmute.industries/oauth/token' \
--header 'Content-Type: application/json' \
--data-raw '{
    "audience": "https://platform.transmute.industries",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "grant_type": "client_credentials"
}'

The response looks something like this:

{
  "access_token": "YOUR_ACCESS_TOKEN",
  "scope": "create:credentials issue:credentials verify:credentials read:credentials",
  "token_type": "Bearer",
  "expires_in": 86400
}

By including this access token in the response header, you can now make authenticated calls to the remaining API endpoints. GET /organizations, for example, returns all metadata of the application’s organization:

curl --location --request GET 'https://platform.transmute.industries/organizations' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Note that you can also authenticate directly through OpenAPI Specification, which enables API calls from the OAS's "Try" buttons.

Postman also has a build in API authentication feature which can be enabled simply by importing the VDP Application's Postman environment file.

Application Update

Your new Application is now listed on the Applications page.

Accessing the Application details page.

From its ellipsis menu, choose view.

Application details.

The Application details page allows you to:

• Update the Name and Description metadata.

• See the Application's scopes (but not change them).

• Delete the Application.

If Name or Description has been changed, click Update to save the changes.

Application Deletion

Deletion of Application.

Finally, an Application can be deleted either from within the Application details page or directly from the ellipsis menu. Client Credentials from a deleted Application can no longer be used for authentication.