SDK overview

DNSid has open-source Go, TypeScript, and Python SDKs (Apache-2.0), the core of the Developer Kit. Each covers the same core surface - verify DNSid domains, sign HTTP requests, and mint DNSid JWTs. The Go module (github.com/dnsid-ai/dnsid-go) is the reference implementation for protocol behavior.

Full API references: Go · TypeScript · Python.

Install

Go

go get github.com/dnsid-ai/dnsid-go

TypeScript

npm install @dnsid-ai/sdk @dnsid-ai/transport

Python

pip install "git+https://github.com/dnsid-ai/dnsid-py.git"

The package is not on PyPI yet, so install it from the repository; pip builds it from source. For AWS KMS-backed keys, add the aws extra: pip install "dnsid[aws] @ git+https://github.com/dnsid-ai/dnsid-py.git".

• Go 1.26.6+ - single module with oidc, httpsig, webbotauth, jose, log, and log/c2sptlog packages, plus the separately tagged key/aws submodule for AWS KMS.
• TypeScript - Node.js 22+, dual ESM/CJS builds. @dnsid-ai/transport is the Node DNS/HTTPS transport; the root SDK is runtime-neutral. Capability-specific packages (registry, OIDC, transparency log, AWS KMS keys) install separately - each guide page names the package its snippets need.
• Python 3.11+ - a single dnsid package; the [aws] extra adds AWS KMS support.

Create an identity manager

Use an identity manager to verify peers and act as your own identity. Load an identity provisioned with dnsid from the CLI’s files, or supply configuration and keys yourself.

From the CLI’s files

The dnsid CLI stores the identity’s publication settings and key files in its config directory. The SDK reads ~/.dnsid/config.json, follows its current-domain pointer to the per-domain config when present, and loads the matching key. Pass a directory to use a different location.

Go

// Import github.com/dnsid-ai/dnsid-go/config.
idm, err := config.IdentityManagerFromDnsid(ctx, "", dnsid.Config{}, config.Dependencies{})
if err != nil {
    log.Fatal(err)
}

TypeScript

import { createNodeIdentityManagerFromDnsid } from '@dnsid-ai/sdk/node';

const idm = await createNodeIdentityManagerFromDnsid();

Python

from dnsid import identity_manager_from_dnsid

manager = identity_manager_from_dnsid()

For DNSid Local, run your code under dnsid local run or load dnsid local env into your shell and use the environment constructor. It reads the identity, key location, DNS, CA, and log policy from the CLI’s DNSID_* exports. See the local quickstart for runnable examples. For an identity loaded from CLI files, configure trust for its lifecycle log before verifying domains.

From explicit configuration

All three SDKs accept a config shape - Config in Go, DnsidConfig in TypeScript and Python - with these sections:

• identity - your own publication settings: domain, governance identifier, log reference, and status URL. Omit it for a verification-only manager.
• verification - status re-check interval, DNSSEC mode, and the counterparty allowlist. The zero value is spec-strict.
• transport - custom DNS server and CA bundle for the SDK-managed resolver and fetcher.

Pair the config with a key provider (local file-backed keys, AWS KMS, or your own implementation) to act as the identity. Publishing requires a status URL and the identity’s lifecycle-log reference. Use the reference assigned by your log; the sample stream ID below is illustrative. Generate a fresh, opaque stream ID for each C2SP identity instance:

Go

kp, err := dnsid.LoadOrCreateLocalKeyProvider("keys.json", dnsid.JoseAlgEdDSA)
if err != nil {
    log.Fatal(err)
}

idm, err := dnsid.NewIdentityManager(dnsid.Config{
    Identity: &dnsid.IdentityConfig{
        Domain:       "agent.example",
        GovernanceID: "example.com",
        LogRef:       "c2sp-tlog:public:https://log.example.com#EREREREREREREREREREREQ",
        StatusURL:    "https://agent.example/.well-known/dnsid/status.json",
    },
}, kp)
if err != nil {
    log.Fatal(err)
}

TypeScript

import { createNodeIdentityManager, LocalKeyProvider } from '@dnsid-ai/sdk/node';

const idm = await createNodeIdentityManager(
  {
    identity: {
      domain: 'agent.example',
      governanceId: 'example.com',
      logRef: 'c2sp-tlog:public:https://log.example.com#EREREREREREREREREREREQ',
      statusUrl: 'https://agent.example/.well-known/dnsid/status.json',
    },
  },
  { keyProvider: await LocalKeyProvider.load('keys.json', true) },
);

Python

from dnsid import DnsidConfig, IdentityConfig, IdentityManager, LocalKeyProvider

manager = IdentityManager(
    DnsidConfig(
        identity=IdentityConfig(
            domain="agent.example",
            governance_id="example.com",
            log_ref="c2sp-tlog:public:https://log.example.com#EREREREREREREREREREREQ",
            status_url="https://agent.example/.well-known/dnsid/status.json",
        ),
    ),
    LocalKeyProvider.load("keys.json", create_if_missing=True),
)

These examples set up an identity and its key. Verification also needs a trusted reader for the lifecycle log named by the record’s lr= reference. Publish self-managed records covers the entity key and ek/ku URLs needed to publish draft 01 records. A verify-only manager doesn’t need a key of its own (Verify a domain).

Combine configuration sources

TypeScript and Python accept a deployment JSON file through createNodeIdentityManagerFromFile('dnsid.json') or identity_manager_from_file("dnsid.json"). The file can contain dnsid, logTrust, and registry sections; an identity also needs a key provider passed to the constructor.

To combine sources, load each separately, merge the results, and construct the manager. If two sources set the same field, the one merged last wins; fields it leaves unset retain their earlier values. Log trust is replaced as a whole. The constructor applies defaults and validates the result. Go supports environment and CLI-directory loading.

What the SDKs handle

• Key management via the KeyProvider interface (local file-backed keys, AWS KMS)
• DNSid TXT record creation, parsing, and signature verification (publishing self-managed records)
• JWKS fetching and caching
• Status checks against the signed status URL
• Domain verification through IdentityManager.VerifyDomain
• Counterparty acceptance - an optional allowlist of accountable entities (governance ID plus optional entity-key pins) enforced on every verification
• Lifecycle-log verification via the C2SP transparency-log binding
• RFC 9421 HTTP Message Signatures and the Web Bot Auth profile
• OIDC token minting and verification through the SDK OIDC profile

How the packages are organized

The three SDKs cover the same capabilities but package them differently: Go is one module with subpackages, TypeScript is one npm package per capability (install what you use), and Python is one package with everything included.

Capability	Go	TypeScript	Python
Verification, records, keys	core module	@dnsid-ai/sdk + @dnsid-ai/transport	dnsid
OIDC tokens	oidc	@dnsid-ai/oidc	included
HTTP Message Signatures (RFC 9421)	httpsig	@dnsid-ai/http-signatures	included
Web Bot Auth	webbotauth	@dnsid-ai/web-bot-auth	included
JOSE (DNSid JWTs)	jose	@dnsid-ai/jose	included
Registry client	core module	@dnsid-ai/registry	included
C2SP transparency log	log/c2sptlog	@dnsid-ai/log-c2sp-tlog	dnsid.c2sp_tlog
AWS KMS keys	key/aws submodule	@dnsid-ai/key-aws	dnsid[aws] extra
GCP KMS keys	-	@dnsid-ai/key-gcp	-

Each guide page names the package its snippets need; the full per-language surface is in the API references.

Verify a domainVerify peer domains in all three languages.

Sign HTTP requestsRFC 9421 signing and verification in all three languages.

Publish self-managed recordsThe pure-protocol publication path.

Key providersLocal keys, AWS KMS, and the key lifecycle.

Go API referenceThe full dnsid-go surface.

TypeScript API referenceAll @dnsid-ai packages.

Python API referenceThe full dnsid package surface.