Marketplace

Once your integration is complete, you can market it to thousands of PDK dealers through our integration marketplace, which is available directly within the pdk.io web interface. Each application within the marketplace is represented by an integration tile. Below is a screenshot of the integration tile for the Microsoft Entra integration.

In addition to making your integration more discoverable, an integration tile will also provide the following technical benefits:

• Dealers will be able to easily enable your integration with the flip of a switch. This is equivalent to authorizing your application by adding a permission, but it doesn't require dealers to know the email address associated with your integration.
• Dealers and customers will be able to easily and securely pass their system ID to your application via the configuration URL.

Configuration

When users click the configure button on your integration tile, they will be redirected to your configuration URL, which is hosted by your application. This URL must be registered by the PDK software integrations team (integrations@prodatakey.com). The behavior of the configuration URL will depend on the needs of your application. For example, you may need to authenticate the user in order to connect their PDK system to the correct user account. The configuration flow is outlined in the steps below.

Step 1: Receive a configuration token

When users are redirected to your application, a token query string parameter is appended to the configuration URL. Your application can exchange this encrypted token for the user's system ID. In the example below, the registered configuration URL is https://example.com/configure.

GET https://example.com/configure?token={{configuration_token}} HTTP/1.1

Step 2: Decrypt the configuration token

The decrypted payload of the configuration token can be retrieved with the following request.

Request

GET https://accounts.pdk.io/api/payload?token={{configuration_token}} HTTP/1.1
Authorization: Bearer {{id_token}}

Parameter	Location	Type	Required	Description
configuration_token	Query	String	Yes	The configuration token.
id_token	Header	String	Yes	A valid ID token.

Response

The response includes the systemId, which your application can use to complete the configuration.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "systemId": "2b6c14b2-ce6d-4109-ab4e-b95a65b048d3",
  "iat": 1708465125,
  "exp": 1708465425,
  "iss": "https://accounts.pdk.io/"
}

Property	Type	Description
systemId	String	The system ID.
iat	String	A Unix timestamp (in seconds) representing the time at which the token was issued.
exp	String	A Unix timestamp (in seconds) representing the time at which the token will expire.
iss	String	The token issuer.

Step 3: Return the user to PDK

Once the user has completed the configuration within your application, you can return the user to the integrations tab in pdk.io to complete the experience.

GET https://pdk.io/systems/{{system_id}}/settings/integrations HTTP/1.1

Parameter	Location	Type	Required	Description
system_id	Path	String	Yes	The system ID.