SHDWsdk Feature Reference & Engineering Documentation
Search across every feature in SHDWsdk—from non-blocking Scope 3 carbon telemetry and the 4 automated AI-BOM discovery layers to EU AI Act / NIST AI RMF documentation, CycloneDX / SPDX exports, customer statements, buyer requests and integrations.
Interactive CLI Setup Wizard (npx @shdwsdk/sdk init / npx shdw-init)
Configure .env / .env.local, generate a ready-to-use AI client wrapper (src/lib/shdw.ts), and verify live telemetry connectivity in under 60 seconds.
- •Prompts interactively in your terminal for your SHDW API key (shdw_live_*), primary cloud data center region (22 EU/US/APAC/LATAM grids), and primary AI model (11 featured models; any model id works).
- •Safely detects .env.local (or .env) and upserts SHDW_API_KEY and SHDW_GRID_REGION without modifying or overwriting any unrelated environment variables or comments.
- •Generates a provider-tailored boilerplate file (default: src/lib/shdw.ts) pre-wired with ShdwTelemetryClient and shdw.wrapClient(), then sends a 1500ms-guarded validation ping to confirm your API key and network route.
- 1Open your terminal in your project's root directory (Windows PowerShell, macOS Terminal, or Linux bash).
- 2Run `npx @shdwsdk/sdk init` (or `npx shdw-init`) and follow the 4 prompts.
- 3Import your wrapped AI client from `src/lib/shdw.ts` anywhere in your application.
# Interactive setup wizard npx @shdwsdk/sdk init # Or run directly with flags npx shdw-init --api-key shdw_live_xxx --region eu-west-3 --model claude-sonnet-5-5 --out src/lib/shdw.ts
Non-Blocking Client Wrapper (shdw.wrapClient) & Fail-Silent Guarantee
Wrap OpenAI, Anthropic or Google Gemini clients in one line of code with a strict 1500ms AbortController timeout and automatic 5xx retry buffering.
- •shdw.wrapClient(client) uses a lightweight JavaScript Proxy to observe .create(), .stream(), and .generateContent() calls without mutating your AI SDK client.
- •For standard responses and Server-Sent Events (SSE) streams, @shdwsdk/sdk normalizes input and output token counts in memory and queues an event on a non-blocking microtask.
- •Background network flushes use an AbortController strictly clamped to <= 1500ms. If a 5xx server error or network outage occurs and buffer capacity permits (< 450 events), failed batches are automatically unshifted back onto the buffer for retry.
- 1Create an API key in Settings → Developer Settings & API Keys.
- 2Install @shdwsdk/sdk via npm, pnpm, yarn, or bun.
- 3Wrap your AI client instance with shdw.wrapClient() and use it normally across your application.
import OpenAI from "openai";
import { ShdwTelemetryClient } from "@shdwsdk/sdk";
const shdw = new ShdwTelemetryClient({
apiKey: process.env.SHDW_API_KEY!,
endpoint: "https://www.shdwsdk.ai/api/v1/ingest-telemetry",
defaultGridRegion: "eu-north-1", // or "us-west-2"
defaultWorkloadName: "Enterprise Support Copilot",
timeoutMs: 1500,
});
export const openai = shdw.wrapClient(new OpenAI());Layer 1: Zero-Touch Runtime AI-BOM Auto-Discovery & Zero-Knowledge Prompt Hashing
Automatically populate your AI Bill of Materials (AI-BOM) from live production AI calls without manually typing model versions or prompt hashes.
- •When your wrapped AI client makes a call, @shdwsdk/sdk inspects the request's system instructions (OpenAI system/developer messages, Anthropic system field, or Gemini systemInstruction) in memory.
- •It computes a deterministic SHA-256 digest (prompt_hash_version) locally in ~0.04ms using Web Crypto. Your actual prompt text never leaves your server.
- •The prompt_hash_version and exact model snapshot (e.g., claude-sonnet-5-5) piggyback on the existing telemetry ping (0 extra network requests). The ingest-telemetry Edge Function upserts your AI-BOM inventory. A weights_hash is recorded only if you send one for weights you host; hosted API vendors do not publish weight digests, so none are inferred.
- 1No extra code is required beyond shdw.wrapClient(client).
- 2Optionally pass defaultWorkloadName and defaultEuAiRiskTier in ShdwTelemetryClient config to label the workload in your AI-BOM.
- 3Open the 'AI-BOM & Governance' tab in your Dashboard to view auto-discovered models and prompt version hashes.
// When your app calls openai.chat.completions.create():
const response = await openai.chat.completions.create({
model: "gpt-5.4-mini",
messages: [
{ role: "system", content: "You are a SOC2 security compliance assistant." },
{ role: "user", content: userQuestion },
],
});
// @shdwsdk/sdk hashes the system prompt in memory -> "sha256:8f41c9..."
// and auto-upserts (gpt-5.4-mini, sha256:8f41c9...) into your AI-BOM!Layer 2: RAG & Vector Database Auto-Instrumentation (shdw.wrapVectorStore)
Automatically link Pinecone, Supabase pgvector, Weaviate, Qdrant, and embedding models to your CycloneDX and SPDX 3.0 AI-BOM lineage graphs.
- •Calling shdw.wrapVectorStore(vectorClient, { sourceUrl, embeddingModelId }) registers your active vector knowledge base on the ShdwTelemetryClient instance.
- •Every subsequent LLM telemetry event automatically includes vector_db_connected: true, vector_db_source_url, and embedding_model_id.
- •When you export SPDX 3.0 AI Profile (.spdx.json) or CycloneDX v1.7 (.cdx.json), SHDWsdk automatically generates DatasetPackage nodes with dependsOn and trainedOn relationship edges.
- 1Call shdw.wrapVectorStore() with your Pinecone index, Supabase client, or vector retriever.
- 2Specify the sourceUrl (e.g., https://index.pinecone.io/prod-kb or pgvector://supabase.db/documents) and embeddingModelId (e.g., text-embedding-3-large).
import { Pinecone } from "@pinecone-database/pinecone";
import { ShdwTelemetryClient } from "@shdwsdk/sdk";
const shdw = new ShdwTelemetryClient({ apiKey: process.env.SHDW_API_KEY! });
const pc = new Pinecone({ apiKey: process.env.PINECONE_API_KEY! });
// Automatically links RAG dataset & embedding model to your AI-BOM
export const kbIndex = shdw.wrapVectorStore(pc.index("enterprise-contracts"), {
sourceUrl: "https://index.pinecone.io/enterprise-contracts",
embeddingModelId: "text-embedding-3-large",
workloadName: "Contract RAG Copilot",
});Layer 3: Static Manifest & CI/CD Auto-Scanner (@shdwsdk/sdk/scanner)
Scan package.json or requirements.txt with zero runtime overhead to auto-discover installed AI SDKs and Vector DB clients.
- •detectAiSdksInManifest() lives in a separate tree-shakeable entry point (@shdwsdk/sdk/scanner) so it adds nothing to your production bundle.
- •It inspects package.json (Node.js/TypeScript) and requirements.txt (Python) for OpenAI, Anthropic, Gemini, Mistral and Cohere SDKs and Pinecone, pgvector, Weaviate, Qdrant and Chroma clients.
- •A manifest tells you which vendors you use, not which model versions or endpoints, so the scanner reports vendors only. Confirm the exact model versions you call before adding them to your AI-BOM — or let the runtime SDK add them automatically.
- 1Open the 'AI-BOM & Governance' tab, paste your package.json or requirements.txt and click 'Detect AI SDKs' to pre-fill the registration form, OR
- 2Import detectAiSdksInManifest from '@shdwsdk/sdk/scanner' in CI to flag AI SDKs that aren't yet in your AI-BOM.
import fs from "node:fs";
import { detectAiSdksInManifest } from "@shdwsdk/sdk/scanner";
const { providers, vectorStores } = detectAiSdksInManifest({
packageJsonContent: fs.readFileSync("./package.json", "utf8"),
});
console.log("AI SDKs:", providers, "Vector stores:", vectorStores);Layer 4: Model Integrity & CycloneDX / SPDX Exporters
How model identity, optional weight digests and measured energy are compiled into CycloneDX v1.7 (.cdx.json) and SPDX 3.0 (.spdx.json).
- •Hosted models (OpenAI, Anthropic, Google, …) are identified by provider and exact model version; their vendors do not publish weight digests. For models you host yourself, pass weightsHash ("sha256:<64 hex>") to record a digest you computed.
- •compileCycloneDxMlBom() generates a CycloneDX v1.7 document with machine-learning-model components, SHA-256 hashes only where you supplied them, measured per-model energy/carbon, and RAG data dependencies.
- •compileSpdx3AiBom() generates an SPDX 3.0.1 JSON-LD graph with ai_AIPackage nodes and, for RAG workloads, dataset_DatasetPackage nodes linked by dependsOn. Pass redactInfrastructure: true to replace vector store URLs with vendor names before sharing.
- 1Go to the 'AI-BOM & Governance' tab of your dashboard.
- 2Click 'Export CycloneDX v1.7 (.cdx.json)' or 'Export SPDX 3.0 AI Profile (.spdx.json)' to download audit-ready files immediately.
Scope 3 Energy & Carbon Formula + 22 Global & European Data Center Regions
How generated tokens, model size, datacenter PUE, and regional power grid intensity (EEA, Ember, US EPA eGRID) produce Scope 3 AI emissions estimates, with uncertainty ranges.
- •Inference Energy follows the open-source EcoLogits v0.11.3 methodology: GPU and server energy are modelled from the number of generated (output) tokens and the model's active and total parameter counts, then multiplied by the provider's datacenter PUE. Prompt tokens do not add energy in this methodology.
- •Closed models (OpenAI, Anthropic, Google) don't publish parameter counts, so EcoLogits estimates them as ranges. Every reading stores a min, max and midpoint; dashboards report the midpoint.
- •Each reading records how the model id was matched (exact, alias, normalized, family, or fallback). Unknown models use a wide generic frontier-class range and are flagged as fallback so they can be reviewed.
- •Energy is recomputed on the server from token counts, so reported figures cannot be altered by the client.
- •Scope 3 Carbon: C_scope3 (gCO2e) = E_inf (kWh) * Grid_Intensity (gCO2e/kWh).
- •Supports 22 global regions including 10 European Union, EEA, UK & Swiss regions (Stockholm 28 gCO2e/kWh, Zurich 42, Paris 56, Madrid 162, London 207, Amsterdam 258, Dublin 274, Milan 296, Frankfurt 348, Warsaw 615) calibrated to EEA / Ember / CSRD ESRS E1, plus 6 North American (EPA eGRID) and 6 APAC/LATAM regions.
- 1Choose your default grid region in Settings → Company & Account. It applies to telemetry that doesn't specify a region; set defaultGridRegion in the SDK to override it.
- 2Override region per AI request if needed by passing gridRegion: 'eu-west-3' in shdw.wrapClient(client, { gridRegion: 'eu-west-3' }).
EU AI Act Risk Classification & US NIST AI RMF 1.0 Assessment Matrix
How your EU AI Act tier and 7 NIST AI RMF outcomes are documented: evidenced by telemetry where possible, otherwise self-attested.
- •SHDWsdk tracks 7 NIST AI RMF 1.0 subcategories (GOVERN 1.1, GOVERN 3.2, MAP 1.1, MAP 4.1, MEASURE 2.12, MANAGE 3.1, MANAGE 3.2). Four can be supported automatically by evidence (telemetry and AI-BOM coverage); policy outcomes such as GOVERN 1.1 can only be self-attested by your organization.
- •Each control shows one of three statuses: evidence from telemetry, self-attested (with the date you saved it), or not documented. The AI RMF is voluntary guidance with no certification, so nothing is ever labelled 'verified'.
- •Your EU AI Act risk tier is shown as self-declared.
- 1Open the 'AI-BOM & Governance' tab of your dashboard.
- 2Select your organization's EU AI Act Risk Classification and check the active NIST AI RMF controls implemented by your team.
- 3Click 'Save self-attestation'. Your public trust report shows the attested controls with the date.
Buyer-Facing Public Trust Center (/trust/[slug]) & Embeddable HTML Badge
Share measured AI energy, emissions, your AI-BOM and governance documentation with buyers, backed by a hash-chained audit log — without exposing raw telemetry or infrastructure details.
- •Your trust report (shdwsdk.ai/trust/[your-slug]) shows 30-day estimated energy and emissions with uncertainty ranges, per-model usage, your AI-BOM, NIST AI RMF and EU AI Act documentation, and the integrity status of your audit log. It states clearly that the data is self-reported, not third-party audited.
- •Visitors only receive an aggregated, sanitized report from the public-trust-data Edge Function: no billing or account identifiers, no vector store URLs, no raw telemetry rows. Anonymous database access is fully revoked.
- •Every telemetry entry is linked into a SHA-256 hash chain when ingested and can't be edited afterwards; the report re-verifies the chain each time it is generated.
- •Add a security contact email in Profile & Settings to show it on your report.
- •When your organization has an active Starter, Scale or Enterprise subscription (including during a free trial), enterprise auditors can download your CycloneDX ML-BOM, SPDX 3.0 AI Profile, and Compliance Attestation directly from the Trust Report.
- 1Open the 'Trust Badge' tab of your dashboard to copy the <iframe> embed snippet for your website footer or security portal.
- 2Click 'Trust report' in the top navigation bar to preview what enterprise buyers see.
API Key Encryption, Sliding-Window Rate Limiting & Constant-Time Webhooks
How SHDWsdk protects your telemetry pipeline against key compromise, flood attacks, and timing side-channels.
- •Raw API keys (shdw_live_*) are shown only once at creation; only their SHA-256 digest (key_hash) is stored in PostgreSQL.
- •The ingest-telemetry Edge Function enforces a dual-layer sliding-window rate limit (120 requests / 60s per organization, 600 for partner keys) combining isolate-local burst rejection with the atomic PostgreSQL RPC check_and_increment_ingest_rate_limit, returning HTTP 429 with Retry-After headers on flood attempts.
- •Stripe billing webhooks verify HMAC-SHA256 signatures using a constant-time byte comparison helper (timingSafeEqual) and a 300-second replay window guard.
- 1Create and rotate API keys in Settings → Developer Settings & API Keys.
- 2Keep your raw shdw_live_* key in server-side environment variables (never expose service keys in client-side code).
Python SDK, OpenTelemetry and LiteLLM
Send telemetry without the JavaScript SDK: a Python package, a LiteLLM callback, or existing OpenTelemetry GenAI spans.
- •All integrations send only model ids and token counts. Energy and carbon are always recomputed on the server with the same EcoLogits methodology, so every source produces comparable figures.
- •Python: shdwsdk.instrument(client) wraps OpenAI and Anthropic clients (sync, async and streaming). Events are sent from a background thread with a 1.5s timeout and never raise into your code.
- •OpenTelemetry: POST OTLP/HTTP JSON traces to /api/v1/otlp/v1/traces with an x-shdw-key header. Spans with gen_ai.request.model or gen_ai.response.model and gen_ai.usage.* token counts are ingested; other spans are ignored. Protobuf encoding isn't supported.
- •LiteLLM: ShdwLiteLLMLogger is a CustomLogger; add it to litellm.callbacks or reference shdwsdk.integrations.litellm.proxy_handler_instance in the proxy config.
- •The dashboard's Data completeness card shows how many requests came from each integration.
- 1Python: pip install shdwsdk, set SHDW_API_KEY, call shdwsdk.init() and shdwsdk.instrument(OpenAI()).
- 2OpenTelemetry: set OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/json and the x-shdw-key header (see the install guide).
- 3If two instrumentations record the same call, keep only one so usage isn't counted twice.
import shdwsdk from openai import OpenAI shdwsdk.init() # reads SHDW_API_KEY client = shdwsdk.instrument(OpenAI())
Data completeness: reconcile with provider billing
Show buyers what share of your AI usage SHDWsdk captures by comparing captured tokens with your provider's billed totals.
- •You enter the total tokens (input + output) your provider billed for a period of up to 92 days. SHDWsdk compares it with the tokens captured for that provider in the same period.
- •The latest result per provider appears on your public trust page as '% of billed tokens captured'. Notes stay private.
- •If captured usage is below 95%, an alert can notify you (Integrations → Alerts).
- 1Copy the token total from your provider's usage page for a period.
- 2On the dashboard Overview, click 'Reconcile with provider usage' and enter provider, period and tokens.
Alerts: Slack and signed webhooks
Get notified about buyer requests, telemetry gaps, audit-chain failures, low coverage and new models.
- •Disclosure requests are sent immediately. Other checks run on a daily schedule: no telemetry for 24 hours, audit chain break, coverage below 95%, and a new model in production.
- •Each event is delivered once per destination; failed deliveries are retried on the next run.
- •Webhooks receive JSON with X-SHDW-Event and X-SHDW-Signature: sha256=<hex HMAC-SHA256 of the raw body>, keyed with the destination's signing secret shown in the dashboard.
- •Destination URLs must be public HTTPS hosts; Slack destinations must be hooks.slack.com incoming webhooks.
- 1Open Integrations → Alerts → Add destination, choose Slack or webhook and the events.
- 2Click Test to send a sample alert.
- 3For webhooks, verify the signature before trusting the payload.
import { createHmac, timingSafeEqual } from "node:crypto";
export function verifyShdwSignature(rawBody: string, header: string, secret: string) {
const expected = "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex");
return header.length === expected.length &&
timingSafeEqual(Buffer.from(header), Buffer.from(expected));
}Developer console: pipeline health, drop rates and live events
See what arrives, what's rejected and why, what SDKs drop, when traffic peaks, and a live feed of events.
- •Every ingestion request is counted per hour as accepted or rejected, with the reason: revoked key, rate limited, invalid payload, batch too large or server error. Requests using a revoked key are attributed to that key, so you can see which deployment still has it. Keys that never existed can't be linked to an organization and aren't shown.
- •JS SDK 1.8+ and Python SDK 0.2+ send delivery counters with their normal batches (about once a minute) or on their own every five minutes when idle: events delivered, dropped by reason (buffer full, key rejected, payload rejected, unreachable) and retried. That's where the drop rate comes from; it can't be measured from the server alone.
- •Reports contain counters only, never event contents. Turn them off with deliveryReports: false (JS), delivery_reports=False (Python) or SHDW_DELIVERY_REPORTS=0.
- •The console refreshes every 30 seconds (events every 10) while the tab is visible. Peaks and the hot-spot heat map use your local time zone.
- 1Open Settings → Developer Settings & API Keys → Open console, or press g then d anywhere in the app.
- 2Check the status bar: Healthy, Degraded (more than 2% rejected or 1% dropped in 24 hours) or Stalled (nothing for 24 hours).
- 3Follow the suggested fix next to each rejection reason; outdated SDK versions are flagged in the integrations list.
npm install @shdwsdk/sdk@^1.8.0
pip install -U "shdwsdk>=0.2.0"
// Opt out of delivery counters (JS)
new ShdwTelemetryClient({ apiKey, deliveryReports: false });Carbon accounting export and cost/carbon savings
Monthly activity CSV for carbon accounting tools, and estimates of what switching models would save.
- •The CSV has one row per month, provider, model and grid region with requests, tokens, electricity (with range), grid factor and kgCO2e, labelled Scope 3 Category 1. It's a generic format to map in your tool's importer, not a native integration.
- •The Savings tab applies list prices (checked on the providers' pricing pages) to your actual token volumes and estimates the cost and emissions of moving a share of traffic to a smaller or newer model. It doesn't assess output quality.
- 1Integrations → Carbon accounting export: choose a period and download the CSV (paid plans).
- 2Savings tab: pick an alternative model and a share of traffic; enter prices for models without a list price.
Per-customer Scope 3 emissions statements
Attribute AI calls to the customer they serve and issue each customer a statement of the AI emissions allocated to them.
- •Each telemetry event can carry a customer_ref: your own pseudonymous account id for the customer (emails are rejected).
- •The customer reference is part of the entry's audit hash, so re-attributing a call to a different customer breaks chain verification.
- •Statements include allocated emissions and electricity with ranges, per-model and grid breakdowns, methodology, a statement ID (SHA-256 of its data) and the audit chain head.
- 1JavaScript: pass customerRef per call, or resolveCustomerRef in the client config (e.g. from AsyncLocalStorage).
- 2Python: wrap calls in with shdwsdk.customer(account_id):. OpenTelemetry: set the shdw.customer_ref span attribute. LiteLLM: metadata={'shdw_customer_ref': account_id}.
- 3Open the 'Customer statements' tab, choose a period, optionally give customers display names, and open a statement (paid plans).
const shdw = new ShdwTelemetryClient({
apiKey: process.env.SHDW_API_KEY!,
resolveCustomerRef: () => requestContext.getStore()?.accountId,
});Questionnaire answers and buyer disclosure requests
Draft answers to AI security questions from your data, and handle buyers' requests for your AI documentation.
- •The Questionnaire tab drafts answers to 21 common AI questions from your AI-BOM, telemetry, audit log, governance attestations and coverage. Each answer is marked 'Backed by your data', 'Draft: complete the blanks' or 'Needs your input'; policy questions are never answered for you.
- •Edits are saved for your whole team. Export answers as CSV or Markdown on paid plans.
- •Buyers can click 'Request documents' on your trust page; requests appear in the Requests tab and buyers see your response on their request page. Buyers can also ask vendors that aren't on SHDWsdk at shdwsdk.ai/request.
- 1Open the Questionnaire tab, fill in the blanks, and copy or export answers.
- 2Add a Slack alert for disclosure requests in Integrations → Alerts, then answer them in the Requests tab.
Deployment and model coverage: clouds, private hosting and self-hosted models
Which providers, hosting setups and model types SHDWsdk measures, how unknown models are handled, and what private-cloud and on-premises deployments need.
- •Any vendor: the model vendor (OpenAI, Anthropic, Google, Mistral, Cohere, Meta, DeepSeek, Alibaba, Microsoft, Amazon, xAI, or any other id) is recorded separately from where the model ran: vendor API, Azure, AWS Bedrock, Google Vertex, self-hosted or other. Hosting is detected from OpenTelemetry gen_ai.provider.name, LiteLLM routes and Bedrock/Vertex model ids, or set explicitly.
- •Capture paths: the JavaScript and Python SDKs, LiteLLM (every provider it routes to, including Azure, Bedrock, Vertex, Ollama and vLLM), any OpenAI-compatible client, and OpenTelemetry. OTLP spans are read with the GenAI semantic conventions, so an OpenTelemetry Collector inside a private cloud can forward spans with no application changes.
- •Energy for text generation uses EcoLogits (0.11.3), including open-weight models such as Llama, Mistral, Qwen and Gemma. Models not in the catalog (fine-tunes, renamed deployments) get a wide generic range and are flagged 'fallback' so they can be reviewed. Embeddings, reranking, moderation and transcription use a documented FLOP-based estimate (shdw-flops-v1); image, speech and OCR calls are counted but not yet estimated, and are excluded from emissions rather than reported as zero.
- •Self-hosted models: set your datacenter's PUE in Settings → Developer and send a grid region or a measured gCO2e/kWh, so self-hosted calls aren't charged a cloud provider's efficiency.
- •Private cloud and on-premises: only metadata leaves your network (model id, token counts, timing, region, pseudonymous ids), never prompts or outputs, through a single outbound HTTPS endpoint. Fully air-gapped installations without any outbound connection aren't supported today.
- •Data regions: choose the United States (Oregon) or the European Union (Frankfurt). EU organizations send to the /eu/ endpoints.
- 1Pick a capture path: SDK, LiteLLM, or an OpenTelemetry Collector exporting to /api/v1/otlp/v1/traces with your key.
- 2Set hosting (e.g. azure or self_hosted) if it can't be detected, and your PUE for self-hosted models.
- 3Check the Overview tab's coverage card and the developer console: fallback-matched models and dropped events show there.
exporters:
otlphttp/shdw:
traces_endpoint: https://www.shdwsdk.ai/eu/api/v1/otlp/v1/traces # or /api/v1/... for US
encoding: json
headers:
x-shdw-key: ${env:SHDW_API_KEY}
processors:
attributes/shdw:
actions:
- { key: shdw.hosting, value: azure, action: upsert } # or self_hosted
service:
pipelines:
traces/shdw:
receivers: [otlp]
processors: [attributes/shdw]
exporters: [otlphttp/shdw]Security and data handling: sign-in, regions, subprocessors, retention
What SHDWsdk stores, where it's stored, who processes it, how access is controlled, and how long it's kept.
- •Data collected: model ids, vendor and hosting, token counts, timing, grid region, energy and cost estimates, and your own pseudonymous customer, matter and trace ids. SHDWsdk never receives prompts, completions or documents, and rejects emails in attribution fields.
- •Sign-in: two-factor authentication with any authenticator app, and SAML 2.0 single sign-on (Okta, Microsoft Entra ID, Google Workspace and others). An organization can require MFA, SSO or both; the database enforces it on every request, including the API. The owner keeps password access as a break-glass account.
- •Isolation: every table is protected by PostgreSQL row-level security scoped to the organization; API keys are stored only as SHA-256 digests; the audit log is append-only and hash-chained.
- •Regions: United States (AWS us-west-2, Oregon) or European Union (AWS eu-central-1, Frankfurt). Data is encrypted in transit (TLS 1.2+) and at rest (AES-256).
- •Subprocessors: Supabase (database, authentication, functions; in your data region), Vercel (web hosting and API routing; global edge), Resend (transactional email; US), Stripe (billing; US, billing data only). The current list is published at shdwsdk.ai/docs/security-and-data-handling.
- •Retention: keep everything, or 13 months to 10 years with a verifiable audit log; legal hold; export at any time; deletion 30 days after the owner schedules it.
- •Attestations: SHDWsdk does not yet hold a SOC 2 report or ISO 27001 certificate. A data processing agreement and our controls documentation are available on request at security@shdwsdk.ai.
- 1Turn on two-factor in Settings → Security, then require it for your organization.
- 2To use SSO, send your IdP's SAML metadata URL to security@shdwsdk.ai, then enter your domain in Settings → Security.
- 3Set retention and legal hold in Settings → Data.
Matters, workflows and cost: attribution below the customer
Break usage, cost and emissions down by your customer's matters or projects, and total each multi-step agent run.
- •customer_ref identifies your customer; matter_ref identifies a matter, case or project under that customer. Both must be pseudonymous ids (letters, digits and . _ : / -), never emails or names.
- •trace_id groups every call of one agent run; workflow_name says which workflow it was. OpenTelemetry trace ids and gen_ai.agent.name are used automatically.
- •Cost per call uses your own negotiated prices where you've set them in Settings → Developer, otherwise list prices; the longest matching model id wins. Calls without a price are counted as unpriced, never as free. Cost is stored per call but kept outside the audit chain, so correcting a price never breaks the evidence.
- •The Usage & cost tab totals calls, tokens, emissions and cost by model, vendor, hosting, operation, customer, matter or workflow for the last 30 days.
- 1Return customerRef, matterRef, workflowName and traceId from resolveContext (JavaScript), or use shdwsdk.matter() and shdwsdk.workflow() (Python).
- 2Add your negotiated prices in Settings → Developer → Model prices.
- 3Open Dashboard → Usage & cost and group by Matter or Workflow.
// JavaScript
const shdw = new ShdwTelemetryClient({
apiKey: process.env.SHDW_API_KEY,
resolveContext: () => ({
customerRef: ctx.firmId,
matterRef: ctx.matterId,
workflowName: ctx.workflow,
traceId: ctx.traceId,
}),
});
# Python
with shdwsdk.matter("M-2026-0042", customer_ref="firm-42"), shdwsdk.workflow("Due diligence"):
run_agent()Partner accounts: SHDWsdk for every customer of your platform
Platforms can give each of their customers their own SHDWsdk organization, trust page and statements, managed from one account and fed by one key.
- •A partner account manages client organizations. Each client has its own audit log, AI-BOM, statements, sign-in policy and trust page (private until published).
- •Partner owners and admins administer every client. A client's MFA requirement applies to them; a client's SSO requirement doesn't, because they sign in through the partner.
- •One partner key sends data for every client: each event carries org_slug. Each client has its own audit chain and rate limit, and an unknown slug is rejected rather than written anywhere else. Partner keys get five times the request rate.
- •Clients inherit the partner's plan and follow it when it changes.
- 1Ask us to enable partner access for your organization (partners@shdwsdk.ai).
- 2Add client organizations in Dashboard → Clients.
- 3Send each client's events with your partner key and org_slug set to the client's slug.
// JavaScript
resolveContext: () => ({ orgSlug: tenant.shdwSlug, customerRef: tenant.id })
# Python
with shdwsdk.organization("firm-one"):
...
# OpenTelemetry attribute
shdw.org_slug = "firm-one"Data retention, legal hold, export and deletion
Choose how long the audit log is kept without losing verifiability, pause deletion for litigation, and export or delete everything.
- •Retention: keep everything, or between 13 months and 10 years. A daily job removes older entries from the start of the chain and records a checkpoint with the last removed entry's hash and the totals removed. Verification continues from the checkpoint, so the remaining log stays tamper-evident.
- •Legal hold stops all pruning and deletion until the owner releases it.
- •Export downloads the whole audit log as CSV in chain order with each entry's hash, plus a manifest with the chain head and verification result.
- •Deletion: the owner types the organization's slug to schedule deletion of the organization and all its data 30 days later; owners or admins can cancel until then.
- 1Open Settings → Data.
- 2Pick a retention period or turn on legal hold, then save.
- 3Use Download CSV + manifest before any deletion if you need a copy.
