Interactive Technical Documentation
Authoritative reference for integrating with the ScaleSystems autonomous workforce platform. Covers cryptographic API authentication, agent provisioning nodes, dual-rail ledger settlement, and real-time telemetry webhook delivery.
Every programmatic request to the ScaleSystems control plane is authenticated with a bearer token using the ss_live_ key prefix. Live keys are 256-bit entropy identifiers hashed with SHA-256 at issuance and stored only as HMAC-derived fingerprints in the tenant vault — the full secret is shown exactly once at creation.
Production keys follow the pattern ss_live_followed by 32 hexadecimal characters. Sandbox keys use ss_test_ and route to isolated runtime sandboxes with synthetic ledger entries.
Each key is bound to a tenant scope: agents:write, agents:read, billing:read, and webhooks:manage. Requests outside the granted scope return 403 SCOPE_DENIED.
Mutating endpoints require an additional X-SS-Signature header computed over the canonical request string: HTTP method, path, timestamp, and SHA-256 body digest — all joined with newlines and signed with the key's HMAC secret.
Timestamps must fall within a ±300 second clock-skew window. Replay attempts outside this window are rejected with 401 STALE_TIMESTAMP.
curl -X GET https://api.scalesystems.ai/api/v1/auth/verify \
-H "Authorization: Bearer ss_live_7f3a9c2e1b8d4f6a0c5e9b2d7a1f4c8" \
-H "X-SS-Timestamp: 1720784160" \
-H "X-SS-Signature: sha256=8f14e45fceea167a5a36dedd4bea2543"Agent deployments are provisioned through regional compute nodes orchestrated by the LangGraph cluster manager. A POST /api/v1/agents request allocates a dedicated runtime slot, binds integration credentials, and enforces plan-tier quota guards before the provisioning pipeline begins.
Validates active agent count and token budget against the caller's plan tier before accepting the provision request.
Selects the lowest-latency regional node with available LangGraph cluster capacity in the requested region.
Registers a 30-second heartbeat cycle and wires downstream integration sync targets from the payload.
curl -X POST https://api.scalesystems.ai/api/v1/agents \
-H "Authorization: Bearer ss_live_7f3a9c2e1b8d4f6a0c5e9b2d7a1f4c8" \
-H "Content-Type: application/json" \
-H "X-SS-Idempotency-Key: prov_8c4f2a91e7b3d605" \
-d '{
"agentType": "lead-sentinel",
"runtime": {
"region": "us-east-1",
"modelTier": "production",
"maxConcurrency": 4
},
"entitlements": {
"planTier": "STARTER",
"tokenBudget": 500000
},
"integrations": {
"hubspot": true,
"slackWebhook": "https://hooks.slack.com/services/T00/B00/XXXX"
}
}'HTTP/1.1 201 Created
Content-Type: application/json
X-SS-Request-Id: req_9f2c8a1e4b7d3f60
X-SS-RateLimit-Remaining: 98
{
"id": "agt_4k9m2x7p1q8w3n6r",
"status": "PROVISIONING",
"agentType": "lead-sentinel",
"nodeId": "node_us-east-1a_ss-prod-07",
"apiKeyPrefix": "ss_live_7f3a",
"createdAt": "2026-07-12T11:36:00.000Z",
"runtime": {
"region": "us-east-1",
"heartbeatIntervalMs": 30000,
"langGraphCluster": "lg-cluster-7f3a9c"
},
"billing": {
"ledgerRail": "stripe",
"planTier": "STARTER",
"quotaRemaining": {
"agents": 4,
"tokens": 500000
}
},
"_links": {
"self": "/api/v1/agents/agt_4k9m2x7p1q8w3n6r",
"telemetry": "/api/v1/agents/agt_4k9m2x7p1q8w3n6r/events"
}
}ScaleSystems billing operates on a dual-rail ledger architecture. Both settlement paths — Stripe fiat checkout and BVNK crypto gateway — resolve to a unified entitlement record on the tenant's Auth.js session, ensuring identical quota enforcement regardless of how the customer pays.
| Ledger Rail | Settlement Path | Reconciliation | Entitlement Sync |
|---|---|---|---|
| stripe | Checkout Session → Subscription webhook | checkout.session.completed | JWT plan claim |
| bvnk | Hawk-signed quote → On-chain confirmation | POST /api/v1/pay/summary | JWT plan claim |
Every settlement event carries a rail-specific idempotency key. Stripe events are deduplicated on event.id; BVNK events on transactionRef. Duplicate deliveries update the ledger audit trail but do not double-apply entitlements.
The unified entitlement record drives runtime guards: agent deployment limits, monthly token throughput ceilings, and concurrent inference slot allocation. A downgrade on either rail propagates to all active provisioning nodes within one heartbeat cycle (≤30s).
Real-time execution telemetry is delivered to your registered endpoint via signed webhook payloads. Configure delivery URLs in the dashboard API Key Portal or programmatically through POST /api/v1/webhooks. Events include agent lifecycle transitions, inference run completions, quota threshold warnings, and ledger settlement confirmations.
{
"event": "agent.execution.completed",
"timestamp": "2026-07-12T11:36:42.812Z",
"deliveryId": "wh_del_3a9f1c8e2b7d4a60",
"data": {
"agentId": "agt_4k9m2x7p1q8w3n6r",
"runId": "ss-run-m2x7p1q8-9f2c8a1e",
"status": "RESOLVED_AND_SYNCED",
"computeTokensSpent": 1847,
"executionPath": [
{ "node": "ingress", "durationMs": 12 },
{ "node": "langgraph-orchestrator", "durationMs": 2840 },
{ "node": "downstream-sync", "durationMs": 186 }
]
},
"signature": "v1=9c2e1b8d4f6a0c5e9b2d7a1f4c87f3a"
}Verify every inbound delivery by recomputing the signature field using HMAC-SHA256 over the raw request body with your webhook signing secret (whsec_ prefix). Reject payloads where the computed digest does not match the declared v1= signature prefix.
Failed deliveries are retried with exponential backoff across 72 hours (attempts at 1m, 5m, 30m, 2h, 8h, 24h). Use the deliveryId for idempotent processing on your receiver.