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 panelId = "{{panel_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 = "{{clientId}}";
string clientSecret = "{{clientSecret}}";
string panelId = "{{panelId}}";

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 panel token

An ID token can also be used to get a panel token (cloud nodes are referred to as panels in the API). The following example returns a panel token for a given panel ID, which is the serial number of the corresponding cloud node.

JavaScript

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

C#

string getPanelToken(string panelId, string idToken)
{
  HttpClient client = new();
  HttpRequestMessage request = new(HttpMethod.Post, $"https://accounts.pdk.io/api/panels/{panelId}/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 panel 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 cloud nodes should only need to retrieve a new ID token every 5 minutes. That single ID token can then be used to retrieve panel tokens for every cloud node, and each panel token can be used many times during its 5-minute lifetime.

Step 3: Use the panel token

A panel token can be used to manage the properties of a particular cloud node, including people, credentials, groups, and rules. The following example creates a new person on a given cloud node.

JavaScript

async function createPerson(panelId, panelToken) {
  const response = await fetch(`https://panel-${panelId}.pdk.io/api/persons`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${panelToken}`,
      "Content-Type": "application/json"
    },
    body: '{"firstName":"John","lastName":"Wiegand"}'
  })
}

C#

void createPerson(string panelId, string panelToken)
{
  HttpClient client = new();
  HttpRequestMessage request = new(HttpMethod.Post, $"https://panel-{panelId}.pdk.io/api/persons");
  request.Headers.Add("Authorization", $"Bearer {panelToken}");
  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 panelToken = await getPanelToken(panelId, idToken)
  createPerson(panelId, panelToken)
}

run()

C#

string idToken = getIdToken();
string panelToken = getPanelToken(panelId, idToken);
createPerson(panelId, panelToken);