Getting Started

Getting Started

Install the SDK, understand the two credentials, configure the client, and make a first call end to end.

Install

npm install @ontomorph/dtp-sdk
# pnpm add @ontomorph/dtp-sdk
# yarn add @ontomorph/dtp-sdk
# bun add @ontomorph/dtp-sdk

Runs on Node.js 18+, Bun, Deno, and any modern browser or edge runtime with fetch. No runtime dependencies beyond the bundled HOLON client.

The two credentials

The SDK uses two credentials for two different jobs. For the full model see Concepts.

DTP API key

Identifies your application to the platform. A key beginning dtp_live_ talks to production; dtp_test_ talks to the sandbox. You pass it as apiKey in the constructor, and the SDK sends it as the X-DTP-API-Key header on every twin-core request.

On its own an API key never unlocks patient data. It says who you are, not what you may see.

Get an API key from the developer dashboard.

Grant token

A signed JWT the patient issues through their consent flow. It authorizes access to exactly one twin, scoped to the body systems and event types they approved. You pass it to dtp.twins.connect(grantToken).

No grant token, no patient data.

Configure the client

Only apiKey is required. Everything else has a default or is needed only for a specific feature.

// client.ts
import { DTP } from "@ontomorph/dtp-sdk";

const dtp = new DTP({
  apiKey: process.env.DTP_API_KEY, // required, dtp_live_… or dtp_test_…
});

The full option set:

apiKey

Required. Your DTP API key (dtp_live_… or dtp_test_…). Sent as X-DTP-API-Key on twin requests.

baseUrl

Twin-core endpoint. Defaults to https://api.ontomorph.com.

identityUrl

Identity-consent endpoint used by dtp.keys. Defaults to https://api.ontomorph.com.

sessionToken

A Zitadel user JWT. Required only for dtp.keys.*.

holonApiUrl

HOLON base URL. Required only for dtp.holon.

holonApiKey

HOLON API key (holon_…). Required only for dtp.holon.

timeout

Per-request timeout in milliseconds. Defaults to 30000.

Your first call, end to end

// first-call.ts
import { DTP } from "@ontomorph/dtp-sdk";

const dtp = new DTP({ apiKey: process.env.DTP_API_KEY });

// A patient issues you a grant token; connect to their twin with it.
const twin = await dtp.twins.connect(grantToken);

twin.grant.twinId;  // the twin this grant authorizes
twin.grant.systems; // e.g. ["cardiovascular"], or null for all

// Read one body system.
const cardio = await twin.systems.get("cardiovascular");
console.log(cardio.events.length, "cardiovascular events");

connect decodes the grant locally and returns fast. The token is verified server-side on the first data request (here, systems.get), so the grant claims on twin.grant are available right away.

Next: Guides for each capability, Concepts for the domain model, API-Reference for exact signatures.