Architecture

Some SDK functionality — including policy management and authorization decisions — is provided through a platform service client rather than through the core SDK. This page explains the difference and when you'll use each.

Core SDK vs. Platform Service Client

	Core SDK	Platform Service Client
What it does	Wraps and unwraps TDF-protected data	Manages platform resources (policy, keys, authorization)
Calls platform	Some operations (e.g. key unwrap, service discovery)	Always — all methods are remote gRPC calls
Examples	CreateTdf, LoadTdf	GetNamespace, GetDecision, ListKeyAccessServers

This is the same pattern used by cloud provider SDKs — you instantiate a typed client once (analogous to new S3Client() in AWS), then call methods on it to manage remote resources.

gRPC is a high-performance open-source remote procedure call framework. It uses HTTP/2 for transport and Protocol Buffers for serialization, enabling strongly-typed service contracts across languages.

Initializing the SDK client

Go

import (
    "github.com/opentdf/platform/sdk"
    // Plus the service-specific package for each call, e.g.:
    "github.com/opentdf/platform/protocol/go/policy/namespaces"
    "github.com/opentdf/platform/protocol/go/authorization"
)

client, err := sdk.New("http://localhost:8080",
    sdk.WithClientCredentials("client-id", "client-secret", nil),
)
if err != nil {
    log.Fatal(err)
}
defer client.Close()

Java

import io.opentdf.platform.sdk.SDK;
import io.opentdf.platform.sdk.SDKBuilder;

SDK sdk = SDKBuilder.newBuilder()
    .platformEndpoint("http://localhost:8080")
    .clientSecret("client-id", "client-secret")
    .useInsecurePlaintextConnection(true) // dev only — remove in production
    .build();

JavaScript

import { AuthProviders, OpenTDF } from '@opentdf/sdk';
import { PlatformClient } from '@opentdf/sdk/platform';

const authProvider = await AuthProviders.clientSecretAuthProvider({
    clientId: 'client-id',
    clientSecret: 'client-secret',
    oidcOrigin: 'http://localhost:8080/auth/realms/opentdf',
});

// OpenTDF eagerly binds DPoP keys to the auth provider.
// Await ready before creating PlatformClient.
const client = new OpenTDF({ authProvider, platformUrl: 'http://localhost:8080' });
await client.ready;

const platform = new PlatformClient({
    authProvider,
    platformUrl: 'http://localhost:8080',
});