Key, sandbox, webhook, claim read.

1. 1. Create a key

   Keys start with sk_sandbox_. Pick only the scopes you need; anything outside the allowlist below is refused.

   create a sandbox keyCopy

   # 1. Create a sandbox key pair (signed-in, verified organization).
   # The response shows the secret key once. A fresh synthetic-data sandbox
   # tenant is created for the pair; no real patient data is in it.
   curl -X POST https://your-sandbox-origin.example/api/developer/keys \
     -H "Content-Type: application/json" \
     -H "Cookie: $SESSION" \
     -d '{ "name": "my-integration", "scopes": ["claims:read"] }'

2. 2. Get an access token

   token exchangeCopy

   # 2. Exchange the key for a short-lived access token (15 minutes).
   curl -X POST https://your-sandbox-origin.example/api/v1/token \
     -H "Authorization: Bearer $SHTEG_API_KEY"

   200 OKCopy

   {
     "access_token": "eyJ...",
     "token_type": "Bearer",
     "expires_in": 900,
     "scope": "claims:read"
   }

3. 3. Subscribe to events

   Endpoint management is a dashboard-session call today; managing endpoints with an access token (webhooks:manage) follows.

   register a webhook endpointCopy

   # 3. Register a webhook endpoint (signed-in session with the
   # integrations:write permission). The signing secret is returned once.
   curl -X POST https://your-sandbox-origin.example/api/webhook-subscriptions \
     -H "Content-Type: application/json" \
     -H "Cookie: $SESSION" \
     -d '{ "url": "https://example.com/shteg/webhooks", "event_types": ["claim.*"] }'

4. 4. Read a claim

   read one claimCopy

   # 4. Read a claim from your sandbox tenant (scope: claims:read).
   curl https://your-sandbox-origin.example/api/v1/claims/$CLAIM_ID \
     -H "Authorization: Bearer $ACCESS_TOKEN"

# TypeScript (@shteg/sdk) — generated from /openapi.json
npm install @shteg/sdk

import { ShtegClient } from "@shteg/sdk";

const shteg = new ShtegClient({
  baseUrl: "https://your-sandbox-origin.example",
  token: () => getAccessToken(), // called before every attempt
});
const status = await shteg.clearinghouse.claimStatus({ path: { id: claimId } });

# Python (shteg) — standard library only, Python 3.9+
pip install shteg

from shteg import Shteg

client = Shteg(base_url="https://your-sandbox-origin.example", token=get_access_token)
status = client.clearinghouse.claim_status(claim_id)

• Retried: 408, 429 and 5xx, honouring Retry-After (seconds or HTTP-date) up to 30 seconds.
• GET is retried. PUT and DELETE are retried only when the spec marks the operation idempotent. A POST is never retried unless you pass an Idempotency-Key and the operation dedupes on it. Retry eligibility comes from the generated operation table, not from a call option.
• Lists that use the { object: "list", data, next_cursor } envelope page with paginate / listAll.

The packages are not on a public registry yet; until they are, install from the repository checkout (packages/sdk, packages/sdk-python).

• Creating a key pair creates its own organization and clinic, seeded with five clearly labelled synthetic patients and one claim each across draft, submitted, paid and denied.
• Every synthetic record is marked as demo data; MRNs start with SBX-. No real person is in a sandbox.
• There is no password login into a sandbox tenant. The key pair is the only way in.
• No live money moves and no clearinghouse submission leaves a sandbox. Production keys are a separate approval.

{
  "id": "evt_...",
  "object": "event",
  "type": "claim.paid",
  "api_version": "2026-10-20",
  "created_at": "2026-10-20T12:00:00.000Z",
  "clinic_id": "cln_...",
  "data": {
    "object_id": "clm_...",
    "object_type": "claim",
    "status": "PAID",
    "previous_status": "SUBMITTED"
  }
}

• Subscribe to exact types or to <object>.*; an empty filter receives every type.
• Deliveries for one object arrive in order: a later one waits until the earlier one is delivered or exhausted.
• Failed deliveries are retried 7 times after 1m, 5m, 30m, 2h, 6h, 12h, 24h (with jitter), then marked dead. Replay re-sends the same delivery and event ids, so dedupe on the event id.

1. Read the raw body bytes before any JSON parsing.
2. Reject a timestamp more than 300 seconds from your clock.
3. Compute the HMAC with your endpoint secret and compare in constant time. During rotation the header can carry several signatures; accept a match against either secret.
4. Answer 2xx only after verifying. Anything else is retried on the schedule above.

import { verifyWebhookSignature } from "@shteg/sdk";

const raw = await request.text(); // the exact raw body, never re-serialized
const signingSecret = loadSecret("shteg-webhook"); // your secret store
const result = await verifyWebhookSignature({
  body: raw,
  signature: request.headers.get("X-Shteg-Signature-256"),
  timestamp: request.headers.get("X-Shteg-Timestamp"),
  secret: [signingSecret], // pass old + new while rotating
});
if (!result.ok) return new Response(null, { status: 401 });

from shteg import verify_webhook_signature

result = verify_webhook_signature(
    raw_body,  # bytes exactly as received
    headers.get("X-Shteg-Signature-256"),
    headers.get("X-Shteg-Timestamp"),
    [secret],  # pass old + new while rotating
)
if not result.ok:
    return 401

Inbound partner webhooks (payment processor, EMR bridge, fax) use a different header; see Webhooks.

• The token exchange (POST /api/v1/token) allows 30 requests per minute per client.
• A limited request gets 429 with Retry-After and X-RateLimit-Limit / -Remaining / -Reset. Both SDKs wait for Retry-After.
• There is no published per-tenant quota across the data APIs yet. Tokens last 15 minutes; reuse one instead of exchanging per request.