Quickstart

What is Konnektr Graph?

Konnektr Graph is a high-performance, Azure Digital Twins-compatible digital twin runtime in our hosted cloud. It provides:

Full ADT API compatibility — use existing Azure Digital Twins SDKs
Real-time eventing — stream twin state changes
Query engine — powerful Cypher over Apache AGE
Managed infrastructure — no setup required

Prerequisites

A Konnektr account at ktrlplane.konnektr.io
A Graph resource provisioned from your organization dashboard
Auth0 client credentials (machine-to-machine app) for your organization

Get your Graph endpoint

After your resource is deployed, you’ll receive a unique endpoint:

https://your-resource-id.api.graph.konnektr.io

You can open the Graph Explorer at:

https://explorer.graph.konnektr.io?x-adt-url=your-resource-id.api.graph.konnektr.io

Authentication (Auth0)

Konnektr Graph uses Auth0, not Azure AD. Do not use DefaultAzureCredential.

Use these values for token requests:

Token endpoint: https://auth.konnektr.io/oauth/token
Audience: https://graph.konnektr.io
Grant type: client_credentials (M2M) or Device Code (user auth)

Copy‑paste code samples

The following samples are concise and tested. They follow the same format you’ll find in the Konnektr Control Plane’s resource page.

cURL

# 1) Get an access token (Client Credentials)
ACCESS_TOKEN=$(curl -s -X POST \
    -H "content-type: application/json" \
    -d '{
        "client_id": "YOUR_CLIENT_ID",
        "client_secret": "YOUR_CLIENT_SECRET",
        "audience": "https://graph.konnektr.io",
        "grant_type": "client_credentials"
    }' \
    https://auth.konnektr.io/oauth/token | jq -r .access_token)

# 2) Upload a simple DTDL model (Room)
curl -s -X POST \
    -H "authorization: Bearer $ACCESS_TOKEN" \
    -H "content-type: application/json" \
    --data '[
        {
            "@id": "dtmi:com:sample:Room;1",
            "@type": "Interface",
            "@context": ["dtmi:dtdl:context;3"],
            "displayName": "Room",
            "contents": [
                { "@type": "Property", "name": "name", "schema": "string" },
                { "@type": "Property", "name": "temperature", "schema": "double" }
            ]
        }
    ]' \
    https://your-resource-id.api.graph.konnektr.io/models

# 3) Create a simple twin using that model
curl -s -X PUT \
    -H "authorization: Bearer $ACCESS_TOKEN" \
    -H "content-type: application/json" \
    --data '{
        "$dtId": "room-1",
        "$metadata": { "$model": "dtmi:com:sample:Room;1" },
        "name": "Sample Room",
        "temperature": 21.5
    }' \
    https://your-resource-id.api.graph.konnektr.io/digitaltwins/room-1

# 4) Query twins (returns the twin we just created)
curl -s -X POST \
    -H "authorization: Bearer $ACCESS_TOKEN" \
    -H "content-type: application/json" \
    --data '{ "query": "SELECT * FROM digitaltwins" }' \
    https://your-resource-id.api.graph.konnektr.io/query

Python

# Install: pip install requests
import requests

# 1) Get access token
token_url = "https://auth.konnektr.io/oauth/token"
token_data = {
        "client_id": "YOUR_CLIENT_ID",
        "client_secret": "YOUR_CLIENT_SECRET",
        "audience": "https://graph.konnektr.io",
        "grant_type": "client_credentials"
}
token_response = requests.post(token_url, json=token_data)
access_token = token_response.json().get("access_token")
headers = {"Authorization": f"Bearer {access_token}", "Content-Type": "application/json"}

# 2) Upload DTDL model
models_url = "https://your-resource-id.api.graph.konnektr.io/models"
model_payload = [
        {
                "@id": "dtmi:com:sample:Room;1",
                "@type": "Interface",
                "@context": ["dtmi:dtdl:context;3"],
                "displayName": "Room",
                "contents": [
                    { "@type": "Property", "name": "name", "schema": "string" },
                    { "@type": "Property", "name": "temperature", "schema": "double" }
                ]
        }
]
requests.post(models_url, json=model_payload, headers=headers)

# 3) Create twin
put_twin_url = "https://your-resource-id.api.graph.konnektr.io/digitaltwins/room-1"
twin_payload = {
        "$dtId": "room-1",
        "$metadata": { "$model": "dtmi:com:sample:Room;1" },
        "name": "Sample Room",
        "temperature": 21.5
}
requests.put(put_twin_url, json=twin_payload, headers=headers)

# 4) Query twins
query_url = "https://your-resource-id.api.graph.konnektr.io/query"
query_payload = {"query": "SELECT * FROM digitaltwins"}
query_response = requests.post(query_url, json=query_payload, headers=headers)
print(query_response.json())

JavaScript/Node.js

// Install: npm install axios
import axios from 'axios';

// 1) Get access token
const tokenUrl = 'https://auth.konnektr.io/oauth/token';
const tokenData = {
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
    audience: 'https://graph.konnektr.io',
    grant_type: 'client_credentials'
};
const { data: token } = await axios.post(tokenUrl, tokenData);
const accessToken = token.access_token;
const headers = { Authorization: `Bearer ${accessToken}`, 'Content-Type': 'application/json' };

// 2) Upload DTDL model
await axios.post('https://your-resource-id.api.graph.konnektr.io/models', [
    {
        '@id': 'dtmi:com:sample:Room;1',
        '@type': 'Interface',
        '@context': ['dtmi:dtdl:context;3'],
        displayName: 'Room',
        contents: [
            { '@type': 'Property', name: 'name', schema: 'string' },
            { '@type': 'Property', name: 'temperature', schema: 'double' }
        ]
    }
], { headers });

// 3) Create twin
await axios.put('https://your-resource-id.api.graph.konnektr.io/digitaltwins/room-1', {
    '$dtId': 'room-1',
    '$metadata': { '$model': 'dtmi:com:sample:Room;1' },
    name: 'Sample Room',
    temperature: 21.5
}, { headers });

// 4) Query twins
const { data } = await axios.post('https://your-resource-id.api.graph.konnektr.io/query', { query: 'SELECT * FROM digitaltwins' }, { headers });
console.log(data);

C#

// Install: dotnet add package System.Net.Http.Json
using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text.Json;

var http = new HttpClient();

// 1) Get access token
var tokenResp = await http.PostAsJsonAsync("https://auth.konnektr.io/oauth/token", new {
        client_id = "YOUR_CLIENT_ID",
        client_secret = "YOUR_CLIENT_SECRET",
        audience = "https://graph.konnektr.io",
        grant_type = "client_credentials"
});
var tokenJson = JsonDocument.Parse(await tokenResp.Content.ReadAsStringAsync());
var accessToken = tokenJson.RootElement.GetProperty("access_token").GetString();
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);

// 2) Upload DTDL model
var modelPayload = new [] {
        new {
                @id = "dtmi:com:sample:Room;1",
                @type = "Interface",
                @context = new [] { "dtmi:dtdl:context;3" },
                displayName = "Room",
                contents = new object[] {
                        new { @type = "Property", name = "name", schema = "string" },
                        new { @type = "Property", name = "temperature", schema = "double" }
                }
        }
};
await http.PostAsJsonAsync("https://your-resource-id.api.graph.konnektr.io/models", modelPayload);

// 3) Create twin
var twinPayload = new {
        $dtId = "room-1",
        $metadata = new { $model = "dtmi:com:sample:Room;1" },
        name = "Sample Room",
        temperature = 21.5
};
await http.PutAsJsonAsync("https://your-resource-id.api.graph.konnektr.io/digitaltwins/room-1", twinPayload);

// 4) Query twins
var queryPayload = new { query = "SELECT * FROM digitaltwins" };
var queryResp = await http.PostAsJsonAsync("https://your-resource-id.api.graph.konnektr.io/query", queryPayload);
Console.WriteLine(await queryResp.Content.ReadAsStringAsync());

Test your connection

# Basic connectivity test
try:
        # Reuse "client" from your SDK setup if using Azure SDKs
        # For raw REST, you can call /models and count results
        import requests
        resp = requests.post("https://your-resource-id.api.graph.konnektr.io/query", json={"query": "SELECT * FROM models"}, headers=headers)
        print(f"✅ Connected successfully! Status: {resp.status_code}")
except Exception as e:
        print(f"❌ Connection failed: {e}")

First actions to try

Upload DTDL models
Create twins
Build relationships
Run queries
Configure event routes and sinks

See the how‑to guides for step‑by‑step examples.

Helpful links

Documentation: https://docs.konnektr.io/docs/graph/
API Reference: https://docs.konnektr.io/docs/graph/reference/api
Using Azure Digital Twins SDKs: https://docs.konnektr.io/docs/graph/how-to-guides/using-azure-digital-twins-sdks
Authentication guide: https://docs.konnektr.io/docs/graph/getting-started/authentication
Graph Explorer: https://explorer.graph.konnektr.io

Note: This page consolidates content that previously lived in "Quickstart" and "First Steps" for a simpler start.

Alternative deployment options

Self-Hosted: Need full control? See the self-hosted deployment guide
Migration: Coming from Azure Digital Twins? See the migration guide

Quickstart

On this page