The Aurigraph DLT SDK is the first-class integration surface for building on the Aurigraph enterprise distributed ledger. It provides native, multi-language clients — TypeScript, Java, Python and Go in the V12 tree today, with a mobile client planned — over a modern gRPC/HTTP2 + Protobuf transport, with RFC 7807 structured errors throughout. Access is governed by an organization-scoped API-key model: an authenticated developer registers an organization and becomes its OWNER, keys are minted under role-gated controls (OWNER > ADMIN > MEMBER), and every request is checked against a precise scope catalog — seven auto-approved read scopes plus six admin-gated write/mint scopes — enforced server-side before any protected operation executes. This paper describes the developer problem the SDK solves, its architecture, the organization-keys and RBAC model, its security posture, and how to get started. It reflects the platform as built on the V12 branch as of 2026-10-20; where a specific client method is illustrative rather than contract-verified, it is labelled as such.
V12
Most distributed-ledger platforms ship one language SDK well, a second adequately, and leave the rest to the community. Integrators outside the favored ecosystem then either wait for third-party clients that lag the protocol, or hand-generate stubs from raw Protobuf definitions — a fragile, undocumented path that re-implements retry logic, error handling, and authentication in every shop.
For an enterprise platform tokenizing real-world assets (RWA) across regulated jurisdictions, that is not workable. Banks, RWA issuers, DMRV (digital monitoring, reporting & verification) providers, and channel operators need a governed, auditable, least-privilege way to integrate — one where key custody, role separation, and scope enforcement are built in, not bolted on.
The Aurigraph DLT SDK exists to remove that tax. It gives developers a consistent conceptual surface across languages, a governed credential model that maps to how organizations actually delegate access, and a transport and error contract designed for production reliability rather than demo convenience.
The SDK is maintained as native, first-party clients (aurigraph-sdk/ on V12) in:
aurigraph-sdk/
Each client exposes the same conceptual operations — connect, authenticate, submit transactions, query registry and channel state, and (where authorized) mint — so a developer fluent in one language can read code written in another. The vocabulary is deliberately consistent across languages.
Real-time and high-throughput communication uses gRPC over HTTP/2 with Protobuf message contracts, in line with the platform's transport standard. HTTP/2 multiplexing, binary Protobuf framing, and streaming make this materially more efficient than JSON-over-HTTP for the request volumes enterprise integrations generate, and Protobuf schemas give both sides a typed, versioned contract. A REST/JSON surface remains available for onboarding and administrative operations (organization and key management live under /api/v11/sdk/*).
/api/v11/sdk/*
The Protobuf contract is open — teams may generate their own stubs from the published .proto files. However, the recommended path is the native SDKs, because generated stubs are, by design, thin wrappers: they provide no language-idiomatic surface (futures vs. CompletableFuture, callbacks vs. async/await), no built-in retry/idempotency wiring, and no compatibility layer to absorb subtle schema evolution. The native SDKs wrap the generated core with idiomatic ergonomics and production concerns (retries, idempotency, error mapping) so that each team does not re-implement them.
.proto
CompletableFuture
async/await
Note: the precise set of production-hardening features (offline queue, idempotency keys, circuit breakers, telemetry hooks) is an active roadmap area; treat any specific feature not confirmed against a shipped client version as a design goal rather than a guarantee.
The defining feature of the SDK's access model is that keys are organization-registered, not anonymously minted. This turns the SDK from a shared password into a team product with clear ownership, least-privilege membership, and an audit trail.
POST /api/v11/sdk/orgs
POST/GET/PATCH/DELETE /api/v11/sdk/orgs/{orgId}/users
POST /api/v11/sdk/orgs/{orgId}/keys
GET /api/v11/sdk/orgs/{orgId}/keys
DELETE /api/v11/sdk/orgs/{orgId}/keys/{keyId}
The raw secret is shown once at mint time and must be stored securely by the caller. Keys are presented on the wire as:
Authorization: ApiKey <orgId>:<rawKey>
Two distinct scope concepts exist in the platform, and it is worth being exact about both:
1. The SDK scope catalog (~13 strings) — the fine-grained scopes checked on SDK endpoints. These partition into seven auto-approved read scopes (usable immediately at registration, no admin review) and six admin-gated write/mint scopes (require explicit approval before use):
registry:read
registry:write
dmrv:read
dmrv:write
stats:read
mint:token
channels:read
channels:write
contracts:read
contracts:write
health:read
ai:chat
ai:read
When an organization requests scopes, the platform partitions the request into an approved subset (usable now) and a pending subset (awaiting admin action) — so a bootstrap integration can start reading immediately while mutating scopes wait for review.
2. The legacy ApiKeyScope enum (four values) — a separate, coarser classification: READ, WRITE, ADMIN, and FULL_ACCESS (where FULL_ACCESS is equivalent to READ + WRITE + ADMIN combined). This coarse enum coexists with the fine-grained catalog above; the catalog is the mechanism used for per-endpoint SDK enforcement.
ApiKeyScope
READ
WRITE
ADMIN
FULL_ACCESS
Keys are minted per organization, tied to a role, and the raw secret is displayed only once — the server stores a salted hash (BCrypt), never the plaintext. Revocation is immediate via the DELETE .../keys/{keyId} endpoint. Because issuance is role-gated and last-owner-guarded, an organization cannot be left orphaned and members cannot silently escalate their own privileges. Partner-signup, scope-approval, and deactivation events are written to a tamper-evident audit trail, so the trust chain from registration to revocation is auditable end to end.
DELETE .../keys/{keyId}
Every protected SDK request passes through an API-key authentication filter and a scope checker that requires the endpoint's declared scope (for example, requireScope(ctx, "mint:token")) before the handler runs. Enforcement is server-side and deny-by-default: a key that lacks the required scope never reaches the protected logic. This mirrors the platform's broader deny-by-default posture on value, key, and mint operations.
requireScope(ctx, "mint:token")
All error responses follow RFC 7807 (application/problem+json) with a consistent field set (type, title, status, detail, instance, error code, trace/request identifiers, service, timestamp). An insufficient-scope rejection returns a 403 with error code ERR_SDK_AUTH_004, giving integrators a machine-readable signal rather than an opaque failure — so client code can distinguish "you need to request this scope" from a transport or availability error.
application/problem+json
ERR_SDK_AUTH_004
The flow is: register an organization → mint a key with the scopes you need → call the ledger with the SDK. Below are short illustrative snippets per language. The organization- and key-management calls are the real REST contract (/api/v11/sdk/*); the higher-level client method names (e.g. client.registry.query()) are illustrative of the intended surface and should be checked against the published client reference for your SDK version.
client.registry.query()
import { AurigraphClient } from "@aurigraph/sdk"; // orgId + rawKey obtained from POST /api/v11/sdk/orgs/{orgId}/keys const client = new AurigraphClient({ endpoint: "https://dlt.aurigraph.io", apiKey: `${orgId}:${rawKey}`, // wire form: Authorization: ApiKey <orgId>:<rawKey> }); // Auto-approved read scope: registry:read const asset = await client.registry.get("asset-123"); // illustrative surface console.log(asset.status);
var client = AurigraphClient.builder() .endpoint("https://dlt.aurigraph.io") .apiKey(orgId + ":" + rawKey) // Authorization: ApiKey <orgId>:<rawKey> .build(); // Requires the admin-gated mint:token scope MintResult result = client.tokens().mint(mintRequest); // illustrative surface System.out.println(result.tokenId());
from aurigraph import AurigraphClient client = AurigraphClient( endpoint="https://dlt.aurigraph.io", api_key=f"{org_id}:{raw_key}", # Authorization: ApiKey <orgId>:<rawKey> ) # Auto-approved read scope: dmrv:read readings = client.dmrv.list(channel_id="ch-1") # illustrative surface for r in readings: print(r.id, r.value)
If a call returns 403 ERR_SDK_AUTH_004, the key lacks the required scope — request the admin-gated scope through your organization's OWNER/ADMIN, or use a key that already carries it.
403 ERR_SDK_AUTH_004
Items above that are not yet confirmed in a shipped client version should be read as design goals.
The Aurigraph DLT SDK treats integration as a first-class, governed capability rather than an afterthought. Native multi-language clients (TypeScript, Java, Python, Go) over gRPC/HTTP2 + Protobuf give developers an idiomatic, efficient surface; the organization-scoped key model gives enterprises the ownership, role separation, least-privilege scopes, and audit trail that regulated RWA work demands; and RFC 7807 errors make failures machine-actionable. Anonymous, ungoverned minting never belonged in that world — and the SDK is built so it never has to.
Explore: About · Products · Features · Whitepapers · Sustainability · Tokenized carbon credits · Real-world asset tokenization · SDK · Blog · Plain-text site index · Sitemap · Contact: contact@aurigraph.io