Code Tutorial

This tutorial provides a working knowledge of the API through a series of minimal code examples.

Step 1: Get an ID token

An ID token can be used to manage organizations within PDK. The following example uses the client credentials authentication flow to get an ID token with a single request.

JavaScript

const clientId = "{{client_id}}"
const clientSecret = "{{client_secret}}"
const systemId = "{{system_id}}"

async function getIdToken() {
  const response = await fetch("https://accounts.pdk.io/oauth2/token", {
    method: "POST",
    headers: {
      Authorization: "Basic " + btoa(`${clientId}:${clientSecret}`),
      "Content-Type": "application/x-www-form-urlencoded"
    },
    body: "grant_type=client_credentials"
  })
  const data = await response.json()
  return data.id_token
}

C#

using System.Text;
using System.Text.Json.Nodes;

string clientId = "{{client_id}}";
string clientSecret = "{{client_secret}}";
string systemId = "{{system_id}}";

string getIdToken()
{
  HttpClient client = new();
  HttpRequestMessage request = new(HttpMethod.Post, "https://accounts.pdk.io/oauth2/token");
  request.Headers.Add("Authorization", "Basic " + Convert.ToBase64String(Encoding.UTF8.GetBytes($"{clientId}:{clientSecret}")));
  request.Content = new StringContent("grant_type=client_credentials", null, "application/x-www-form-urlencoded");
  HttpResponseMessage response = client.Send(request);
  JsonNode data = JsonNode.Parse(response.Content.ReadAsStream())!;
  return data["id_token"]!.ToString();
}

Step 2: Get a system token

An ID token can also be used to get a system token. The following example returns a system token for a given system ID, which can be obtained from the pdk.io URL.

JavaScript

async function getSystemToken(systemId, idToken) {
  const response = await fetch(`https://accounts.pdk.io/api/systems/${systemId}/token`, {
    method: "POST",
    headers: { Authorization: `Bearer ${idToken}` }
  })
  const data = await response.json()
  return data.token
}

C#

string getSystemToken(string systemId, string idToken)
{
  HttpClient client = new();
  HttpRequestMessage request = new(HttpMethod.Post, $"https://accounts.pdk.io/api/systems/{systemId}/token");
  request.Headers.Add("Authorization", $"Bearer {idToken}");
  HttpResponseMessage response = client.Send(request);
  JsonNode data = JsonNode.Parse(response.Content.ReadAsStream())!;
  return data["token"]!.ToString();
}

tip

Rather than retrieving fresh ID and system tokens before every request, applications can increase speed and efficiency by re-using tokens whenever possible. For example, an application interacting with a large number of systems should only need to retrieve a new ID token every 5 minutes. That single ID token can then be used to retrieve system tokens for every system, and each system token can be used many times during its 5-minute lifetime.

Step 3: Use the system token

A system token can be used to manage the properties of a particular system, including holders, credentials, groups, and rules. The following example creates a new holder on a given system.

JavaScript

async function createHolder(systemId, systemToken) {
  const response = await fetch(`https://systems.pdk.io/${systemId}/holders`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${systemToken}`,
      "Content-Type": "application/json"
    },
    body: '{"firstName":"John","lastName":"Wiegand"}'
  })
}

C#

void createHolder(string systemId, string systemToken)
{
  HttpClient client = new();
  HttpRequestMessage request = new(HttpMethod.Post, $"https://systems.pdk.io/{systemId}/holders");
  request.Headers.Add("Authorization", $"Bearer {systemToken}");
  request.Content = new StringContent("{\"firstName\":\"John\",\"lastName\":\"Wiegand\"}", null, "application/json");
  HttpResponseMessage response = client.Send(request);
}

Step 4: Put it all together

These examples can be combined to create a functional script with no dependencies.

JavaScript

async function run() {
  const idToken = await getIdToken()
  const systemToken = await getSystemToken(systemId, idToken)
  createHolder(systemId, systemToken)
}

run()

C#

string idToken = getIdToken();
string systemToken = getSystemToken(systemId, idToken);
createHolder(systemId, systemToken);