Quickstart
Keep the key on your server.
The module runs in Node.js, Deno and compatible server runtimes with Fetch and Web Crypto. It is deliberately not a browser SDK: a sandbox key must never be embedded in JavaScript, iOS bundles or public repositories.
curl --fail --remote-name \
https://clarity.audecius.com/developer/clarity-developer-client.mjsimport { ClarityDeveloperClient } from "./clarity-developer-client.mjs";
const clarity = new ClarityDeveloperClient({
apiKey: process.env.CLARITY_API_KEY,
});
const status = await clarity.status();
const preview = await clarity.previewTool({
schema: "clarity.tool/v1",
name: "Study outline",
entry: "study.outline",
consequenceClass: "C1",
permissions: ["profile.read"],
display: {
layout: "list",
icon: "list.bullet.rectangle",
color: "blue",
columns: [{ name: "Item", type: "text" }],
},
});Client surface
Every published operation is represented.
- Read
status · profile · sessions · usage · webhooks · tools- Tool lifecycle
validateTool · previewTool- Delivery
testWebhook- Raw escape hatch
request(path, options)- Specification
- Download OpenAPI 3.1
Security contract
No hidden retries. No secret persistence.
- Key
- Kept only in the calling server's memory; the client writes it neither to disk nor to logs.
- Timeout
- 12 seconds by default, configurable from 1 to 30 seconds; AbortSignal is supported.
- Request ID
- Every call carries a secure correlation ID and returns the server-confirmed ID.
- Errors
- ClarityDeveloperError contains the status, stable code, request ID and optional validation details.
- Redirects
- Fetch uses redirect:error so credentials do not follow a redirect to another domain.
- Mutations
- The client does not retry POST requests automatically.
Boundary
A client is not unrestricted platform access.
The client talks only to the sandbox. Keys are project-bound, expiring and revocable. Tools remain declarative, C0–C2 and human-reviewed. Private account, health, school and family data, native StoreKit entitlements and production credentials stay excluded.