Skip to main content
Sigilum provides official SDKs for TypeScript/Node.js, Python, and Go. All SDKs implement a common contract based on RFC 9421 HTTP Message Signatures, ensuring consistent behavior across languages.

​
Supported SDKs

SDKRuntimePackage/ModuleStatus
TypeScriptNode.js >= 20@sigilum/sdkSupported
PythonPython >= 3.11sigilumSupported
GoGo 1.23sigilum.local/sdk-goSupported
JavaJDK 21id.sigilum:sdk-javaNot yet supported

​
Common Contract

All supported SDKs implement the same RFC 9421-style signing profile:

​
Signing Algorithm

  • Algorithm: Ed25519 signatures
  • Headers: RFC 9421-style Signature-Input and Signature
  • Components: Signs method, URI, and custom Sigilum headers

​
Required Sigilum Headers

Every signed request includes these headers:
  • sigilum-namespace - The namespace that owns the agent identity
  • sigilum-subject - The principal who triggered this action (user/system ID)
  • sigilum-agent-key - The agent’s Ed25519 public key (ed25519:...)
  • sigilum-agent-cert - Base64url-encoded agent certificate (version, namespace, DID, keyId, proof)

​
Body Integrity

Requests with a body include:
  • content-digest - SHA-256 digest in RFC 9421 format: sha-256=:base64digest:
  • The content-digest header is included in signed components for tamper detection

​
Subject Semantics

sigilum-subject is not decorative—it identifies who triggered this action:
  • Use a stable principal ID (for example: customer-12345, system-scheduler)
  • Gateway policy can apply subject-level controls using this value
  • If omitted, SDKs default to the signer’s namespace for backward compatibility
  • Platforms/integrations are responsible for setting this value accurately
Never use random or per-request values for subject. Use consistent user/system identifiers.

​
Identity Hierarchy

Sigilum uses a DID-based identity model: 
namespace -> service -> agent -> subject
DID Format: did:sigilum:{namespace}:{service}#{agent}#{subject} Example: did:sigilum:mfs:narmi#davis-agent#customer-12345 This hierarchy enables:
  • Fine-grained audit trails
  • Subject-level policy enforcement
  • Service isolation within namespaces
  • Agent-specific access controls

​
Signature Verification

All SDKs provide server-side verification with deterministic failure metadata:

​
Error Codes

Verification failures return machine-readable codes:
CodeMeaning
SIG_CONTENT_DIGEST_MISMATCHRequest body was tampered with
SIG_VERIFICATION_FAILEDSignature cryptographically invalid
SIG_CERT_INVALIDAgent certificate proof failed
SIG_TIMESTAMP_OUT_OF_RANGESignature expired or not yet valid
SIG_REPLAY_DETECTEDNonce already seen (replay attack)
SIG_NAMESPACE_MISMATCHNamespace header doesn’t match cert
SIG_SUBJECT_MISSINGRequired subject header missing

​
Replay Protection

SDKs support nonce-based replay detection: 
const nonceStore = new Set<string>();

const result = verifyHttpSignature({
  url: request.url,
  method: request.method,
  headers: request.headers,
  body: await request.text(),
  strict: {
    maxAgeSeconds: 300, // 5 minutes
    nonceStore,
  },
});

if (!result.valid) {
  console.error(result.code, result.reason);
}

​
Retry Helpers

All SDKs provide portable retry helpers for idempotent operations:
  • Function: retryWithBackoff / retry_with_backoff / RetryWithBackoff
  • Status codes: Retries 429, 502, 503, 504 by default
  • Backoff: Exponential with jitter
  • Safety: Requires idempotent: true when attempts > 1
import { retryWithBackoff, shouldRetryHttpStatus } from "@sigilum/sdk";

const response = await retryWithBackoff(
  async () => {
    return agent.sigilum.fetch("/v1/namespaces/alice", { method: "GET" });
  },
  {
    idempotent: true,
    attempts: 3,
    shouldRetryResult: (res) => shouldRetryHttpStatus(res.status),
  },
);

​
CLI Tools

Supported SDKs ship with CLI tools for identity management:

​
Initialize Identity

sigilum init johndee
sigilum init johndee --json  # machine-readable output

​
List Identities

sigilum list
sigilum list --json  # machine-readable output

​
Authentication Model

Signed headers prove agent identity and authenticity. Some endpoints require additional auth:
  • Signed headers: Required on all protected endpoints (/v1/*, /.well-known/*)
  • Bearer tokens: Some endpoints also require Authorization: Bearer <service_api_key>
  • Example: POST /v1/claims requires both signed headers AND service API key

​
Test Vectors

Shared conformance test vectors ensure cross-SDK compatibility:
  • sdks/test-vectors/http-signatures-rfc9421.json - RFC 9421 signing conformance
  • sdks/test-vectors/identity-record-v1.json - Identity record compatibility
Coverage includes:
  • Fragment stripping from URLs
  • Method/body component profile checks
  • Replay/timestamp strictness
  • Tamper detection (method/header/body)
  • Forward-compatible identity record loading

​
Next Steps

TypeScript SDK

Install and use the TypeScript/Node.js SDK

Python SDK

Install and use the Python SDK

Go SDK

Install and use the Go SDK

Build docs developers (and LLMs) love

Get started for freeTalk to us